Java集合框架的Collection分支详解

package java.util;
// 继承了 Iterable，意味着所有 Collection 实现类都可以使用 for-each 循环
public interface Collection<E> extends Iterable<E> {
    // .......
}

public class ArrayList<E> extends AbstractList<E>
        implements List<E>, RandomAccess, Cloneable, java.io.Serializable
{
    // 默认初始容量
    private static final int DEFAULT_CAPACITY = 10;
    // 共享的空数组实列
    private static final Object[] EMPTY_ELEMENTDATA = {};
    //默认大小的空数组实列
    private static final Object[] DEFAULTCAPACITY_EMPTY_ELEMENTDATA = {};
    // 用于存储元素的数组缓冲区。ArrayList 的容量就是这个数组的长度。
    // transient 关键字表示该字段不会被序列化
    transient Object[] elementData;
    // ArrayList 中包含的元素数量
    private int size;
    // ..........
}

public ArrayList(){
    this.elementData = DEFAULTCAPACITY_EMPTY_ELEMENTDATA;
}

//JDK 1.6
public ArrayList() {
        this(10); // 直接调用带容量的构造函数，传入 10
}
public ArrayList(int initialCapacity) {
    super();
    if (initialCapacity < 0)
        throw new IllegalArgumentException("Illegal Capacity: "+ initialCapacity);
    this.elementData = new Object[initialCapacity]; // 立即创建一个长度为 10 的数组
}

public ArrayList(int initialCapacity) {
    if (initialCapacity > 0) {
        // 如果初始容量大于0，创建对应大小的Object数组
        this.elementData = new Object[initialCapacity];
    } else if (initialCapacity == 0) {
        // 如果初始容量为0，使用预定义的空数组常量
        this.elementData = EMPTY_ELEMENTDATA;
    } else {
        // 如果初始容量为负数，抛出非法参数异常
        throw new IllegalArgumentException("Illegal Capacity: "+ initialCapacity);
    }
}

public ArrayList(Collection<? extends E> c) {
    // 使用Collection的toArray()方法将传入的集合转换为数组
    Object[] a = c.toArray();
    // 将数组长度赋值给 size,同时判断数组长度是否为0
    // 如果数组长度不等于 0,则向下继续执行
    // 否则，就使用预定义的空数组EMPTY_ELEMENTDATA
    if ((size = a.length) != 0) {
        //判断集合本身是否是ArrayList
        //如果是，就直接使用其内部数组（elementData）
        //否则，使用Arrays.copyOf()创建一个新的数组副本
        //其目的是为了保证新创建的ArrayList的内部数组完全独立，不受原集合影响
        if (c.getClass() == ArrayList.class) {
            elementData = a;
        } else {
            elementData = Arrays.copyOf(a, size, Object[].class);
        }
    } else {
        elementData = EMPTY_ELEMENTDATA;
    }
}

public boolean add(E e) {
    ensureCapacityInternal(size + 1);  // 关键：检查容量是否足够
    elementData[size++] = e; // 将元素放入数组，并增加 size
    return true;
}

private void ensureCapacityInternal(int minCapacity) {
    // 如果elementData 是否是默认的空数组
    if (elementData == DEFAULTCAPACITY_EMPTY_ELEMENTDATA) {
        // 如果是，则将最小容量设置为默认容量(10)和请求容量中的较大值
        // 确保了第一次添加元素时，数组至少有10个元素的空间
        minCapacity = Math.max(DEFAULT_CAPACITY, minCapacity);
    }
    ensureExplicitCapacity(minCapacity);
}

 private void ensureExplicitCapacity(int minCapacity) {
    // 修改计数器，用于迭代器的快速失败机制
    // 快速失败机制（fail-fast）:是一种错误检测机制。当在迭代过程中，
    // 如果检测到集合结构被修改（非迭代器自身的方法导致的修改）                                                               
    // 迭代器会立即抛出ConcurrentModificationException异常，
    // 而不是继续执 行可能导致不确定行为。
    modCount++;
    // 检查是否需要扩容 (所需最小容量大于当前数组的长度)
    if (minCapacity - elementData.length > 0) 
        // 执行扩容操作 grow(int minCapacity)
        grow(minCapacity);
}

private void grow(int minCapacity) {
    // overflow-conscious code
    // 旧容量      
    int oldCapacity = elementData.length; 
    // 新容量 = 旧容量 + 旧容量/2 (即 1.5 倍)
    int newCapacity = oldCapacity + (oldCapacity >> 1); 
    // 如果 1.5 倍后还不够，就用所需的最小容量
    if (newCapacity - minCapacity < 0)
        newCapacity = minCapacity;
    // 处理极端情况，防止新容量超过 Integer.MAX_VALUE
    if (newCapacity - MAX_ARRAY_SIZE > 0)
        newCapacity = hugeCapacity(minCapacity);
    // minCapacity is usually close to size, so this is a win:
    // 关键：复制数组
    elementData = Arrays.copyOf(elementData, newCapacity);
}

public synchronized void addElement(E obj) {
    modCount++;
    ensureCapacityHelper(elementCount + 1);
    elementData[elementCount++] = obj;
}
public synchronized boolean removeElement(Object obj) {
    modCount++;
    int i = indexOf(obj);
    if (i >= 0) {
        removeElementAt(i);
        return true;
    }
    return false;
}
public synchronized void removeAllElements() {
    modCount++;
    // Let gc do its work
    for (int i = 0; i < elementCount; i++)
        elementData[i] = null;
    elementCount = 0;
}
public synchronized E get(int index) {
    if (index >= elementCount)
        throw new ArrayIndexOutOfBoundsException(index);
    return elementData(index);
}
public synchronized E set(int index, E element) {
    if (index >= elementCount)
        throw new ArrayIndexOutOfBoundsException(index);
    E oldValue = elementData(index);
    elementData[index] = element;
    return oldValue;
}
public synchronized E remove(int index) {
    modCount++;
    if (index >= elementCount)
        throw new ArrayIndexOutOfBoundsException(index);
    E oldValue = elementData(index);
    int numMoved = elementCount - index - 1;
    if (numMoved > 0)
        System.arraycopy(elementData, index+1, elementData, index,
                             numMoved);
    elementData[--elementCount] = null; // Let gc do its work
    return oldValue;
}
//...........

public class Vector<E>
    extends AbstractList<E>
    implements List<E>, RandomAccess, Cloneable, java.io.Serializable
{
    protected Object[] elementData; // 存储元素的数组
    protected int elementCount; // 实际元素数量（相当于 ArrayList 中的 size）
    protected int capacityIncrement; // 容量增长系数
    private static final long serialVersionUID = -2767605614048989439L;
    // 定义一个数组理论上的最大容量上限
    // 注意：这个 8 不是一个魔法数字，它是基于对主流 JVM 实现对象内存布局的经验值。
    // 它足够大，可以覆盖大多数虚拟机中数组对象的额外开销。
    private static final int MAX_ARRAY_SIZE = Integer.MAX_VALUE - 8; 
    //...........
}

private void grow(int minCapacity) {
    // overflow-conscious code
    int oldCapacity = elementData.length; // 获取当前数组容量 
    // 计算新容量 newCapacity：
    // 如果设置了capacityIncrement（扩容增量），则新容量 = 旧容量 + capacityIncrement
    // 如果没有设置capacityIncrement（默认为0），则新容量 = 旧容量的2倍
    int newCapacity = oldCapacity + ((capacityIncrement > 0) ?
                                         capacityIncrement : oldCapacity);
    // 检查新容量是否满足最小需求，如果不满足则使用minCapacity
    if (newCapacity - minCapacity < 0)
        newCapacity = minCapacity;
    // 检查新容量是否超过最大数组限制（MAX_ARRAY_SIZE = Integer.MAX_VALUE - 8）
    if (newCapacity - MAX_ARRAY_SIZE > 0)
        newCapacity = hugeCapacity(minCapacity);
    // 使用Arrays.copyOf创建新数组并复制原有元素
    elementData = Arrays.copyOf(elementData, newCapacity);
}

private static class Node<E> {
    E item; // 存储节点的数据
    Node<E> next; // 指向下一个节点的引用
    Node<E> prev; // 指向上一个节点的引用
    // 构造函数：建立车厢之间的连接
    Node(Node<E> prev, E element, Node<E> next) {
        this.item = element; // 设置当前节点的数据
        this.next = next; // 设置下一个节点
        this.prev = prev; // 设置上一个节点
    }
}

public class LinkedList<E>
    extends AbstractSequentialList<E>
    implements List<E>, Deque<E>, Cloneable, java.io.Serializable
{
    transient int size = 0; // 记录LinkedList中元素的数量，初始化为0，表示空链表
    transient Node<E> first; // 头指针，指向链表的第一个节点，若链表为空则为 null
    transient Node<E> last; // 尾指针，指向链表的最后一个节点，若链表为空则为 null
    //........
}

public E get(int index) {
    // 检查传入索引是否有效
    checkElementIndex(index); 
    // 如果索引有效，调用 node(int index) 方法找到对应索引得节点，并返回找到的节点的 item 字段
    return node(index).item; 
}
private void checkElementIndex(int index) {
    // 检查传入索引是否有效（即在指定范围内），无效则抛出IndexOutOfBoundsException的异常
    if (!isElementIndex(index))
        throw new IndexOutOfBoundsException(outOfBoundsMsg(index));
}
private boolean isElementIndex(int index) {
    // 判断索引是否在0到size-1范围内
    return index >= 0 && index < size;
}
Node<E> node(int index) {
    // 根据索引与链表长度的关系决定是从头开始遍历还是从尾开始遍历，以提高查找效率
    // 如果index小于size的一半(size >> 1 (size/2))
    if (index < (size >> 1)) {
        Node<E> x = first;  // 从头节点开始
        for (int i = 0; i < index; i++) // 向后遍历index次
            x = x.next;
        return x;
    // 否则从last节点开始向前遍历
    } else {
        Node<E> x = last; // 从尾节点开始
        for (int i = size - 1; i > index; i--)  // 向前遍历(size-1-index)次
            x = x.prev;
        return x;
    }
}

public void addFirst(E e){
    linkFirst(e); // 将实际元素 e 链接到列表开头
}
public void linkFirst(E e){
    // 保存当前头节点的引用
    final Node<E> f = first; 
    // 创建新的节点，它的 prev 是 null，next 是旧的头节点 f
    final Node<E> newNode = new Node<>(null, e, f); 
    // 让 first 指针指向新节点，新节点成为新的头
    first = newNode;
    // 处理边界情况：如果链表原来为空
    if (f == null)
        // 链表为空时，新节点既是头也是尾
        last = newNode;
    else
        // 如果链表不为空，让旧头节点的 prev 指向新节点
        f.prev = newNode;
    size++; // 增加 size 大小
    modCount++; // 修改计数器，用于快速失败
}
public void addLast(E e){
    linkLast(e); // 将实际元素 e 链接到列表尾部
}
void linkLast(E e){
    // 保存当前尾部节点的引用
    final Node<E> f = last;
    // 创建新的节点，它的 prev 是 旧的尾部节点 l，next 是 null
    final Node<E> newNode = new Node<>(l, e, null);
    // 让 last 指针指向新节点，新节点成为新的尾部
    last = newNode;
    // 处理边界情况：如果链表原来为空
    if (l == null)
        // 链表为空时，新节点既是头也是尾
        first= newNode;
    else
        // 如果链表不为空，让旧尾部节点的 next 指向新节点
        l.next= newNode;
    size++; // 增加 size 大小
    modCount++; // 修改计数器，用于快速失败
}

public void add(int index, E element){
    // 检查索引是否越界
    checkPositionIndex(index);
    // 如果插入位置是末尾
    if(index == size)
        linkLast(element); //调用linkLast 方法添加至尾部
    else
        linkBefore(element,node(index)); // 否则，在指定节点前插入
}
private void checkPositionIndex(int index){
    // 检查传入索引是否有效（即在指定范围内），无效则抛出IndexOutOfBoundsException异常
    if(!isPositionIndex(index))
        throw new IndexOutOfBoundsException(outOfBoundsMsg(index));
}
private boolean isPositionIndex(int index){
    // 判断索引是否在0到size范围内
    return index >= 0 && index <= size;
}
void linkBefore(E e, Node<E> succ){
    // 获取目标节点 succ 的前驱节点
    final Node<E> pred = succ.prev;
    // 创建新节点newNode，设置其前驱为pred，后继为succ
    final Node<E> newNode = new Node<>(pred, e, succ);
    // 更新succ的前驱指针指向newNode
    succ.prev = newNode;
    // 目标节点 succ 的前驱节点 pred 是否为null，判断是否在链表头部插入
    if (pred == null)
        first = newNode; // 如果pred为null，说明succ是第一个节点，需要更新first指针
    else
        pred.next = newNode; // 否则，更新pred的后继指针指向newNode
    size++; // 增加链表大小size
    modCount++; // 修改计数modCount，用于快速失败
}

public E removeFirst(){
    // 获取链表头节点，并用 final 修饰，确保引用不会被改变
    final Node<E> f = first; 
    // 检查链表是否为空
    //如果为空（first为null），抛出NoSuchElementException异常
    if (f == null) 
        throw new NoSuchElementException(); 
    //调用unlinkFirst方法实际执行删除操作，返回被删除节点的值
    return unlinkFirst(f); 
}
private E unlinkFirst(Node<E> f){
    // 保存要删除节点的元素值
    final E element = f.item; 
    // 保存下一个节点的引用
    final Node<E> next = f.next;
    // 清空当前节点的数据
    // 显式地将引用置为null可以帮助垃圾回收器更快回收内存
    f.item = null;
    f.next = null; // help GC
    // 将链表的first指针指向下一个节点
    first = next;
    // 如果下一个节点为null，说明链表现在为空
    if (next == null)
        last = null;
    // 否则将下一个节点的前驱指针设为null
    else
        next.prev = null;
    // 更新链表大小和修改次数
    size--;
    modCount++;
    // 返回被删除节点的元素值
    return element;
}
public E removeLast(){
    // 获取链表尾节点，并用 final 修饰，确保引用不会被改变
    final Node<E> l = last;
    // 检查链表是否为空
    //如果为空（last为null），抛出NoSuchElementException异常
    if (l == null)
        throw new NoSuchElementException();
    //调用unlinkLast方法实际执行删除操作，返回被删除节点的值
    return unlinkLast(l); 
}
private E unlinkLast(Node<E> l){
    // 保存要删除节点的值
    final E element = l.item;
    // 保存前一个节点的引用
    final Node<E> prev = l.prev;
    // 清空当前节点的数据
    // 显式地将引用置为null可以帮助垃圾回收器更快回收内存
    l.item = null;
    l.prev = null; // help GC
    // 将链表的last指针指向上一个节点
    last = prev;
    // 如果上一个节点为null，说明链表现在为空
    if (prev == null)
        first = null;
    // 否则将上一个节点的后继指针设为null
    else
        prev.next = null;
    // 更新链表大小和修改次数
    size--;
    modCount++;
     // 返回被删除节点的元素值
    return element;
}

public E remove(int index){
     检查索引是否有效
     checkElementIndex(index);
     // 调用 unlink 方法删除指定位置元素，并返回删除元素的值
     return unlink(node(index));
}
private void checkElementIndex(int index){
    // 检查传入索引是否有效（即在指定范围内），无效则抛出IndexOutOfBoundsException的异常
    if (!isElementIndex(index))
        throw new IndexOutOfBoundsException(outOfBoundsMsg(index));
}
private boolean isElementIndex(int index) {
    // 判断索引是否在0到size-1范围内
    return index >= 0 && index < size;
}
E unlink(Node<E> x){
    // assert x != null;
    // 保存删除目标元素 x及元素本身的前驱和后继引用,使用final修饰，确保引用不会被修改
    final E element = x.item;
    final Node<E> next = x.next;
    final Node<E> prev = x.prev;
    // 如果前驱节点为null，说明要移除的是头节点，则将first指针指向后继节点next
    if (prev == null) {
        first = next;
    // 否则，则将前驱节点的next指针指向当前节点的后继节点next，并断开当前节点与前驱节点的连接
    } else {
        prev.next = next;
        x.prev = null;
    }
    // 如果后继节点为null，说明要移除的是尾节点，则将last指针指向前驱节点prev
    if (next == null) {
        last = prev;
    // 否则，则将后继节点的prev指针指向前驱节点prev，并断开当前节点与后继节点的连接
    } else {
        next.prev = prev;
        x.next = null;
    }
    // 将被移除节点的item设为null，帮助垃圾回收
    x.item = null;
    // 减少链表的大小size
    size--;
    // 增加修改计数modCount（用于迭代时的快速失败机制）
    modCount++;
    // 返回被移除节点的元素值
    return element;
}

public boolean contains(Object o){
     // 调用 indexOf 查找目标元素 o 的索引，并判断目标元素索引不等于 -1
     // 目标元素索引等于 -1，等式不成立，返回 false; 不等于则返回 true
     return indexOf(o) != -1;
}
public int indexOf(Object o){
    // 初始化索引记数器
    int index = 0; 
    // 分别处理查找 null 值和非 null 值的情况，避免出现NullPointerException
    // 处理查找null值的情况
    if (o == null) {
        for (Node<E> x = first; x != null; x = x.next) {
            if (x.item == null)
                return index;
            index++;
        }
    // 处理查找非null值的情况
    } else {
        for (Node<E> x = first; x != null; x = x.next) {
            if (o.equals(x.item))
                return index;
            index++;
        }
    }
    // 未找到元素，返回-1
    return -1;
}

import java.util.LinkedList;
import java.util.ListIterator;
public class ListIteratorDemo {
    public static void main(String[] args){
        LinkedList<String> list = new LinkedList<>();
        list.add("A");
        list.add("B");
        list.add("C");
        list.add("D");
        System.out.println("原始列表: " + list); // [A, B, C, D]
        // 获取 ListIterator，从索引 0 开始
        ListIterator<String> iterator = list.listIterator();
        // 1. 获取第一个元素 "A"
        System.out.println("next: " + iterator.next()); // 返回 A, 光标移到 A 后
        // 光标位置: A | B C D
        // 2. 在当前光标位置（即 A 和 B 之间）插入 "New"
        iterator.add("New"); 
        System.out.println("add后: " + list); // [A, New, B, C, D]
        // 光标位置: A New | B C D
        // 3. 获取下一个元素 "B"
        System.out.println("next: " + iterator.next()); // 返回 B, 光标移到 B 后
        // 光标位置: A New B | C D
        // 4. 获取下一个元素 "C"
        System.out.println("next: " + iterator.next()); // 返回 C, 光标移到 C 后
        // 注意：最后一次返回的是 C，所以接下来的 set 会替换 C
        // 光标位置: A New B C | D
        // 5. 将刚刚获取的 "C" 替换为 "Replace_C"
        iterator.set("Replace_C");
        System.out.println("set后: " + list); // [A, New, B, Replace_C, D]
        // 6. 向后回退：获取前一个元素
        // 此时光标在 C(即Replace_C) 后，前一个就是 Replace_C
        System.out.println("previous: " + iterator.previous()); //返回 Replace_C, 光标回退
        // 光标位置: A New B | Replace_C D
        // 7. 删除刚刚回退获取的元素 "Replace_C"
        iterator.remove();
        System.out.println("remove后: " + list); // [A, New, B, D]
    }
}

public class CopyOnWriteArrayList<E>
    implements List<E>, RandomAccess, Cloneable, java.io.Serializable {
    // 序列化版本号，用于实现 Serializable 接口
    private static final long serialVersionUID = 8673264195747942595L;
    // ReentrantLock 可重入锁，用来保护所有修改操作
    // transient 修饰，表示在序列化时不会保存
    final transient ReentrantLock lock = new ReentrantLock();
    // 存储实际数据的数组
    // volatile关键字确保可见性，即一个线程修改了数组，其他线程能立即看到变化
    private transient volatile Object[] array;
    final Object[] getArray() {
        return array;
    }
    final void setArray(Object[] a) {
        array = a;
    }
    //.............
}

public E get(int index) {
    // 先调用 getArray() 获取 array 引用，不加任何锁
    // 然后调用另一个重载的get方法，传入数组和索引，返回数组中的元素
    return get(getArray(),index);
}
private E get(Object[] a, int index) {
    return (E) a[index];
}

public boolean add(E e) {
    // 获取锁对象
    final ReentrantLock lock = this.lock;
    // 加锁，确保线程安全
    lock.lock();
    try {
        // 获取当前数组
        Object[] elements = getArray();
        // 获取当前数组长度
        int len = elements.length;
        // 创建一个新数组，长度为原数组+1，并拷贝旧数组
        Object[] newElements = Arrays.copyOf(elements, len + 1);
        // 在新数组末尾添加新元素
        newElements[len] = e;
        // 将新数组设置为底层数组
        setArray(newElements);
        return true;
    } finally {
        // 释放锁
        lock.unlock();
    }
}

import java.util.Iterator;
import java.util.List;
import java.util.concurrent.CopyOnWriteArrayList;
public class CopyOnWriteArrayListDemo {
    public static void main(String[] args) {
        List<String> list = new CopyOnWriteArrayList<>();
        list.add("A");
        list.add("B");
        // 迭代器创建时，拿到的是 [A, B] 的快照
        Iterator<String> it = list.iterator(); 
        // 主线程修改了列表
        list.add("C"); 
        while(it.hasNext()) {
            // 只会打印 A 和 B，不会抛出异常，也看不到 C
            System.out.println(it.next()); 
        }
    }
}

public class HashSet<E>
    extends AbstractSet<E>
    implements Set<E>, Cloneable, java.io.Serializable
{
    // 序列化版本号
    static final long serialVersionUID = -5024744406713321676L;
    // HashSet 的核心，实际上使用 HashMap 来存储数据
    // transient 关键字表示 map 不参与序列化
    private transient HashMap<E,Object> map;
    // 一个固定的 Object 对象，作为 HashMap 中所有 value 的占位值
    private static final Object PRESENT = new Object();
    // 创建 HashSet，底层 HashMap 使用默认初始容量（16）和加载因子（0.75）
    public HashSet() {
        map = new HashMap<>();
    }
    // 创建一个包含指定集合元素的 HashSet，根据集合大小计算合适的初始容量，确保不会频繁扩容
    public HashSet(Collection<? extends E> c) {
        map = new HashMap<>(Math.max((int) (c.size()/.75f) + 1, 16));
        addAll(c);
    }
    // 创建 HashSet,允许自定义初始容量和加载因子
    public HashSet(int initialCapacity, float loadFactor) {
        map = new HashMap<>(initialCapacity, loadFactor);
    }
    // 创建 HashSet, 允许自定义初始容量
    public HashSet(int initialCapacity) {
        map = new HashMap<>(initialCapacity);
    }   
}

public boolean add(E e) {
    // 直接用 map 的 put 方法存储元素 e
    // e 是 key, PRESENT 是固定的 value
    return map.put(e, PRESENT)==null;
}
public boolean remove(Object o) {
    // 直接调用 map 的 remove 方法删除元素 o
    return map.remove(o)==PRESENT;
}
public boolean contains(Object o) {
    // 直接调用 map 的 containsKey 方法查找元素 o
    return map.containsKey(o);
}

// Adds the specified element to this set if it is not already present.
public boolean add(E e) {
    return map.put(e, PRESENT)==null;
}

public V put(K key, V value) {
    // 调用hash(key)方法计算键的哈希值
    // 将哈希值、键、值以及其他参数传递给putVal方法
    return putVal(hash(key), key, value, false, true);
}
static final int hash(Object key) {
    int h;
    // 如果 key 是 null，返回 0；否则将 h 右移 16 位并与自身异或（高位运算，减少冲突）
    return (key == null) ? 0 : (h = key.hashCode()) ^ (h >>> 16);
}
// hash: key的哈希值
// key: 要存储的键
// value: 要存储的值
// onlyIfAbsent: 如果为true，则仅在键不存在时才插入
// evict: 是否在插入后执行可能的移除操作（用于LinkedHashMap）
final V putVal(int hash, K key, V value, boolean onlyIfAbsent, boolean evict) {
    Node<K,V>[] tab; Node<K,V> p; int n, i;
    // 检查内部数组table是否为空，如果是则通过resize()初始化
    // resize()会创建一个新的数组并返回
    if ((tab = table) == null || (n = tab.length) == 0)
        n = (tab = resize()).length;
    // 使用(n-1) & hash计算key在数组中的索引位置
    // 如果该位置为空，直接创建新节点放入
    if ((p = tab[i = (n - 1) & hash]) == null)
        tab[i] = newNode(hash, key, value, null);
    // 处理哈希冲突
    else {
        Node<K,V> e; K k;
        // 直接匹配：检查第一个节点是否与要插入的key相同
        if (p.hash == hash && ((k = p.key) == key || (key != null && key.equals(k))))
            e = p; // 记录当前节点
        // 红黑树节点
        else if (p instanceof TreeNode)
            // 调用putTreeVal方法处理
            e = ((TreeNode<K,V>)p).putTreeVal(this, tab, hash, key, value);
        // 链表节点：遍历链表，查找是否已存在相同的key
        else {
            for (int binCount = 0; ; ++binCount) {
                // 如果遍历到链表尾部还没找到重复的，说明元素不重复，挂在尾部
                if ((e = p.next) == null) {
                    p.next = newNode(hash, key, value, null);
                    // 当链表长度达到TREEIFY_THRESHOLD(默认8)时，转换为红黑树
                    if (binCount >= TREEIFY_THRESHOLD - 1) // -1 for 1st
                        treeifyBin(tab, hash);
                    break;
                }
                 // 在链表中判断：Hash值相同 且 (引用相同 或 equals相同)
                if (e.hash == hash &&
                    ((k = e.key) == key || (key != null && key.equals(k))))
                    break; // 找到重复了，跳出循环，e 指向重复节点
                p = e;
            }
        }
        // e 不为 null，说明在 Map 中找到了现有的 Key（即元素重复）
        if (e != null) { // existing mapping for key
            V oldValue = e.value;
            // 根据 onlyIfAbsent 决定是否覆盖（HashSet 永远是覆盖）
            if (!onlyIfAbsent || oldValue == null)
                e.value = value;
            afterNodeAccess(e);
            // 返回旧值，这对 HashSet 意味着 add 失败
            return oldValue;
        }
    }
    // 如果程序能走到这里，说明 e 为 null，是新增节点
    ++modCount; //增加修改计数
    // 检查是否需要扩容
    if (++size > threshold)
        resize();
    afterNodeInsertion(evict);
    return null; // 返回 null，这对 HashSet 意味着 add 成功
}

public class HashMap<K,V> extends AbstractMap<K,V>
    implements Map<K,V>, Cloneable, Serializable 
{
    // 默认初始容量（初始容量为2的4次方）
    static final int DEFAULT_INITIAL_CAPACITY = 1 << 4; // 16
    // 最大容量（最大容量为2的30次方）
    static final int MAXIMUM_CAPACITY = 1 << 30; // 1073741824
    // 默认负载因子（默认的负载因子为0.75，加载因子 = 哈希表中元素数量 / 容量）
    static final float DEFAULT_LOAD_FACTOR = 0.75f;
    // .........
}

// java.util.HashMap
final V putVal(int hash, K key, V value, boolean onlyIfAbsent，boolean evict)
{
    // ......（省略前面的计算索引和处理链表逻辑）
    ++modCount;
    // 插入成功后，size 自增
    // 【核心扩容判断】
    // size：当前元素数量
    // threshold：扩容阈值（容量*负载因子）
    if(++size > threshold)
        resize(); // 触发扩容
    afterNodeInsertion(evict);
    return null;
}

// java.util.HashMap
final Node<K,V>[] resize(){    
    // 获取旧的 table
    Node<K,V>[] oldTab = table; 
    // 获取旧表格（oldTab）的容量
    // 使用三元运算符判断：如果oldTab为null，则oldCap为0；否则为oldTab的长度
    int oldCap = (oldTab == null) ? 0 : oldTab.length; 
    // 获取旧的扩容阈值（threshold）
    // HashMap需要扩容的临界值，通常为容量*加载因子
    int oldThr = threshold;
    // 声明新的容量（newCap）和新的阈值（newThr）
    int newCap, newThr = 0;
    // 如果旧数组不为空
    if (oldCap > 0) {
        // 如果旧容量已经达到最大值，不再扩容
        if (oldCap >= MAXIMUM_CAPACITY) {
            threshold = Integer.MAX_VALUE;
            return oldTab; // 返回旧表格
        }
        // 【核心逻辑】：新容量 = 旧容量左移1位 (即乘以2)
        // (newCap = oldCap << 1) 例如 16 -> 32
        // 如果计算的新容量没达到最大值且旧容量大于默认初始容量，计算新阈值
        else if ((newCap = oldCap << 1) < MAXIMUM_CAPACITY &&
                     oldCap >= DEFAULT_INITIAL_CAPACITY)
            // 新阈值也乘以2
            newThr = oldThr << 1;
    }
    // 当oldThr > 0时，说明HashMap已经被初始化过
    // 这种情况下，新的容量(newCap)直接设置为旧的阈值(oldThr)
    // 注释"initial capacity was placed in threshold"表明初始容量被存储在了阈值中
    else if (oldThr > 0) // initial capacity was placed in threshold
        newCap = oldThr;
    // 初始化时，如果用户没有指定初始容量（即 threshold 为 0）的情况下
    else {
        // 设置默认容量和扩容阈值
        newCap = DEFAULT_INITIAL_CAPACITY;
        newThr = (int)(DEFAULT_LOAD_FACTOR * DEFAULT_INITIAL_CAPACITY);
    }
    // 如果新阈值是 0 (比如使用默认构造函数时)，重新计算
    if (newThr == 0) {
        // 新的容量：(newCap)乘以加载因子(loadFactor)
        float ft = (float)newCap * loadFactor;
        // 使用浮点数ft进行中间计算，避免精度丢失，将计算结果转换为整数赋值给threshold
        newThr = (newCap < MAXIMUM_CAPACITY && ft < (float)MAXIMUM_CAPACITY ?
                    (int)ft : Integer.MAX_VALUE);   
    }
    threshold = newThr; // 更新全局阈值
    Node<K,V>[] newTab = (Node<K,V>[])new Node[newCap]; // 创建新的数组
    table = newTab; // 将新数组赋值给 table
    // 如果旧数组有数据，开始遍历迁移
    if (oldTab != null) {
        for (int j = 0; j < oldCap; ++j) {
            Node<K,V> e;
            // 如果当前位置有元素
            if ((e = oldTab[j]) != null) {
                oldTab[j] = null; // 显式地将引用置为null帮助垃圾回收器更快回收内存
                // 单个节点处理
                if (e.next == null)
                    // 直接计算新位置并放入
                    newTab[e.hash & (newCap - 1)] = e;
                // 红黑树处理
                else if (e instanceof TreeNode)
                    // 调用split方法进行拆分
                    ((TreeNode<K,V>)e).split(this, newTab, j, oldCap);
                // 链表处理
                // 通过维护两个链表(lo和hi)，将元素分别加入对应的链表
                else {
                    // loHead/loTail：保持原索引位置的链表
                    // hiHead/hiTail：需要移动到"原索引+旧容量"位置的链表
                    Node<K,V> loHead = null, loTail = null;
                    Node<K,V> hiHead = null, hiTail = null;
                    Node<K,V> next;
                    do {
                        next = e.next;
                        // 判断元素的位置是否需要移动
                        // 如果(e.hash & oldCap) == 0，说明元素在新数组中的位置不变
                        if ((e.hash & oldCap) == 0) {
                            if (loTail == null)
                                loHead = e;
                            else
                                loTail.next = e;
                            loTail = e;
                        }
                        // 如果(e.hash & oldCap) != 0
                        // 元素需要移动到新位置，新位置 = 原位置 + oldCap
                        else {
                            if (hiTail == null)
                                hiHead = e;
                            else
                                hiTail.next = e;
                            hiTail = e;
                        }
                    } while ((e = next) != null);
                    // 处理低位链表
                    if (loTail != null) {
                        loTail.next = null; // 断开低位链表的最后一个节点的next指针
                        newTab[j] = loHead; // 将低位链表放在新数组的原索引位置
                    }
                    // 处理高位链表
                    if (hiTail != null) {
                        hiTail.next = null; // 断开高位链表的最后一个节点的next指针
                        newTab[j + oldCap] = hiHead; // 将高位链表放在新数组的原索引+oldCap位置
                    }
                }
            }
        }
    }
    return newTab;
}

public class LinkedHashSet<E>
    extends HashSet<E>
    implements Set<E>, Cloneable, java.io.Serializable 
{
    // ..........
}

public class LinkedHashSet<E>
    extends HashSet<E>
    implements Set<E>, Cloneable, java.io.Serializable 
{
    // 序列化/反序列化的版本控制ID
    private static final long serialVersionUID = -2851667679971038690L;
    // 创建一个指定初始容量和加载因子的空LinkedHashSet
    public LinkedHashSet(int initialCapacity, float loadFactor) {
        super(initialCapacity, loadFactor, true);
    }
    // 创建一个指定初始容量，默认加载因子(0.75)的空LinkedHashSet
    public LinkedHashSet(int initialCapacity) {
        super(initialCapacity, .75f, true);
    }
    // 创建一个默认初始容量(16)和默认加载因子(0.75)的空LinkedHashSet
    public LinkedHashSet() {
        super(16, .75f, true);
    }
    // 创建一个包含指定集合所有元素的LinkedHashSet，初始容量设为max(2*c.size(), 11)
    public LinkedHashSet(Collection<? extends E> c) {
        super(Math.max(2*c.size(), 11), .75f, true);
        addAll(c);
    }
    // 可分割迭代器
    @Override
    public Spliterator<E> spliterator() {
        return Spliterators.spliterator(this, Spliterator.DISTINCT | Spliterator.ORDERED);
    }
}

// java.util.HashSet

// 底层存储 Map
private transient HashMap<E,Object> map;


/**
 * 构造一个新的空的链接哈希集合实例。
 * （这个构造函数只给 LinkedHashSet 访问，dummy 没有实际意义）
 */
HashSet(int initialCapacity, float loadFactor, boolean dummy) {
    // 注意这里：new 的不是 HashMap，而是 LinkedHashMap！
    map = new LinkedHashMap<>(initialCapacity, loadFactor);
}

public class HashMap<K,V> extends AbstractMap<K,V>
    implements Map<K,V>, Cloneable, Serializable 
{
    static class Node<K,V> implements Map.Entry<K,V> {
        final int hash; // 存储键的哈希值，用于快速定位
        final K key; // 存储键，用final修饰表示键不可变
        V value; // 存储值，可以被修改
        Node<K,V> next; // 指向下一个节点的引用，用于处理哈希冲突
        //........
    }
}

public class LinkedHashMap<K,V> extends HashMap<K,V> implements Map<K,V>
{
    // 静态内部类
    // 继承自 HashMap.Node，说明其具备了 HashMap 中节点的所有基本特性
    static class Entry<K,V> extends HashMap.Node<K,V>{
        // 新增的两个指针，用于维护双向链表
        // before（前驱指针）：指向前一个节点
        // after（后继指针）：指向后一个节点
        Entry<K,V> before, after;
        // 构造函数
        // 接收四个参数：hash值、键、值和下一个节点
        // 通过 super() 调用父类 HashMap.Node 的构造函数，确保新建节点具备 HashMap 节点的所有基本属性
        Entry(int hash, K key, V value, Node<K,V> next) {
            super(hash, key, value, next);
        }
    }
}

// java.util.linkedHashMap
// 双向链表的头节点
// transient关键字表示这个字段不会被序列化
transient LinkedHashMap.Entry<K,V> head;
// 双向链表的尾节点
// transient关键字表示这个字段不会被序列化
transient LinkedHashMap.Entry<K,V> tail;
// 这是一个 final 字段，决定了 LinkedHashMap 的迭代顺序
// 当为 true 时，按照访问顺序迭代（最近访问的放在最后）
// 当为 false 时，按照插入顺序迭代 （默认为 false）
final boolean accessOrder;

// java.util.LinkedHashMap
Node<K,V> newNode(int hash, K key, V value, Node<K,V> e) {
    // 创建新节点 p
    LinkedHashMap.Entry<K,V> p = new LinkedHashMap.Entry<K,V>(hash, key, value, e);
    // 调用链接方法，把新增节点 p 挂在链表尾部
    linkNodeLast(p);
    return p;
} 
private void linkNodeLast(LinkedHashMap。Entry<K,V> p) {
    LinkedHashMap.Entry<K,V> last = tail; // 保存当前尾节点
    tail = p; // 将新节点p设置为新的尾节点
    if (last == null) // 如果链表为空
        head = p; // 将新节点同时设为头节点
    else { // 如果链表不为空
        p.before = last; // 将新节点的前驱指针指向原尾节点
        last.after = p; // 将原尾节点的后继指针指向新节点
    }
}

// java.util.LinkedHashMap
public V get(Object key) {
    // 声明一个 Node 类型的变量 e,用于存储找到的节点
    Node<K,V> e;
    // 调用 getNode 方法查找节点
    // 如果找不到对应节点（e为null），直接返回null
    if ((e = getNode(hash(key), key)) == null)
        return null;
    // 如果accessOrder为true，表示按照访问顺序排序
    if (accessOrder)
        // 调用 afterNodeAccess(e) 方法将最近访问的节点移到链表末尾
        afterNodeAccess(e);
    // 返回找到的节点的value值
    return e.value;
}
void afterNodeAccess(Node<K,V> e) {    
    LinkedHashMap.Entry<K,V> last;
    // 检查是否需要重新排序（accessOrder为true）且节点不在尾部
    if (accessOrder && (last = tail) != e) {
        // 保存当前节点的前后节点引用
        LinkedHashMap.Entry<K,V> p =
                (LinkedHashMap.Entry<K,V>)e, b = p.before, a = p.after;
        // 将p的after置为null，因为它将成为新的尾节点
        p.after = null;
        // 如果b为null，说明p是头节点，更新头节点为a；否则，将b的after指向a
        if (b == null)
            head = a;
        else
            b.after = a;
        // 如果a不为null，将a的before指向b；否则，更新last为b
        if (a != null)
            a.before = b;
        else
            last = b;
        // 如果last为null，说明链表为空，将头节点head设置为p；否则，将p连接到last之后
        if (last == null)
            head = p;
        else {
            p.before = last;
            last.after = p;
        }
        // 更新尾节点tail为p
        tail = p;
        // 增加修改计数器
        ++modCount;
    }
}

// java.util.LinkedHashMap
abstract class LinkedHashIterator {
    LinkedHashMap.Entry<K,V> next; // 指向下一个要遍历的节点
    LinkedHashMap.Entry<K,V> current; // 当前正在处理的节点
    int expectedModCount; // 预期的修改次数，用于快速失败(fail-fast)机制
    LinkedHashIterator() {
        next = head; // 从双向链表的头节点开始
        expectedModCount = modCount; // 记录创建迭代器时的修改次数
        current = null; // 当前节点初始化为null
    }
    // 判断是否还有下一个元素
    public final boolean hasNext() {
        return next != null;
    }
    final LinkedHashMap.Entry<K,V> nextNode(){
        LinkedHashMap.Entry<K,V> e = next;
        // 检查是否有并发修改
        if (modCount != expectedModCount)
            throw new ConcurrentModificationException();
        if (e == null) 
            throw new NoSuchElementException();
        // 更新当前节点
        current = e; 
        // 移动到下一个节点（通过after指针）
        next = e.after; 
        return e;
    }
}

import java.util.Arrays;
import java.util.LinkedHashSet;
import java.util.Set;
import java.util.TreeSet;
// 插入顺序 vs 排序顺序
public class OrderDemo {
    public static void main(String[] args) {
        String[] letters = {"C", "A", "B", "A"};
        // LinkedHashSet: 维持插入顺序
        Set<String> linkedSet = new LinkedHashSet<>(Arrays.asList(letters));
        System.out.println("LinkedHashSet: " + linkedSet);
        // 输出: [C, A, B] -> 去重了，且 C 在最前面，因为它是第一个插入的
        // TreeSet: 按字典序排序
        Set<String> treeSet = new TreeSet<>(Arrays.asList(letters));
        System.out.println("TreeSet: " + treeSet);
        // 输出: [A, B, C] -> 去重了，且按 A, B, C 排列，完全忽略了插入顺序
    }
}

public class TreeSet<E> extends AbstractSet<E>
    implements NavigableSet<E>, Cloneable, java.io.Serializable
{
    // ..........    
}

public class TreeSet<E> extends AbstractSet<E>
    implements NavigableSet<E>, Cloneable, java.io.Serializable
{
    // TreeSet 内部使用一个 NavigableMap (实际是 TreeMap) 来存储元素
    private transient NavigableMap<E,Object> m;
    // 这个是一个虚拟值，用于在 TreeMap 中关联集合的元素
    // 因为 TreeMap 存储的是键值对，而 TreeSet 只需要键
    private static final Object PRESENT = new Object();
    //.............
}

// java.util.TreeMap
static final class Entry<K,V> implements Map.Entry<K,V> {
    K key;
    V value;
    Entry<K,V> left; // 左子节点
    Entry<K,V> right; // 右子节点
    Entry<K,V> parent; // 父节点
    boolean color = BLACK; // 节点颜色，默认为黑
    Entry(K key, V value, Entry<K,V> parent) {
        this.key = key;
        this.value = value;
        this.parent = parent;
    }
    // .........
}  

// java.util.TreeSet
// 无参构造器，使用自然排序
public TreeSet() {
    this(new TreeMap<E,Object>());
}
// 带比较器的构造器，使用自定义排序
public TreeSet(Comparator<? super E> comparator) {
    this(new TreeMap<>(comparator));
}
// 构造一个包含指定集合元素的新 TreeSet，使用自然排序
public TreeSet(Collection<? extends E> c) {
    this();
    addAll(c);
}
// 构造一个包含指定有序集合元素的新 TreeSet，按照相同顺序
public TreeSet(SortedSet<E> s) {
    this(s.comparator());
    addAll(s);
}
// 包访问权限的构造器，直接传入一个 NavigableMap
// 主要用于子类或者特定场景，比如 headSet, subSet, tailSet 等返回的子集
TreeSet(NavigableMap<E,Object> m) {
    this.m = m;
}

// java.util.TreeSet
public boolean add(E e) {
    // 直接调用底层 TreeMap 的 put 方法
    // 如果之前不存在该 key，则 put 返回 null，add 返回 true (添加成功)
    // 如果之前已存在该 key (根据排序规则)，则 put 返回旧 value，add 返回 false (添加失败，元素已存在)
    return m.put(e,PRESENT) == null;
}

// java.util.TreeMap
public V put(K key, V value) {
    Entry<K,V> t = root; // 从根节点开始
    // 特殊情况：树是空的
    // 此时 new Entry 的 parent 是 null，默认 color 是 BLACK
    // (Entry构造器中 color 默认 BLACK，但在 insert 修正里可能会变)
    if (t == null) {
        compare(key, key); // 类型检查，确保 key 是可比较的
        root = new Entry<>(key, value, null); // 创建根节点
        size = 1;
        modCount++;
        return null;
    }
    int cmp;
    Entry<K,V> parent;
    Comparator<? super K> cpr = comparator;
    // 如果有自定义比较器，使用比较器进行比较
    if (cpr != null) {
        // 遍历树找到合适的插入位置
        do {
            parent = t;
            cmp = cpr.compare(key, t.key);
            if (cmp < 0) // 小，往左走
                t = t.left;
            else if (cmp > 0) // 大，往右走
                t = t.right;
            else // 相等，替换值， TreeSet 这里返回 PRESENT
                return t.setValue(value);
        } while (t != null);     
    }
    // 如果没有自定义比较器，使用键的自然排序
    else {
        // 键不能为null 且 键必须实现Comparable接口
        if (key == null)
            throw new NullPointerException();
            Comparable<? super K> k = (Comparable<? super K>) key;
        do {
            parent = t;
            cmp = k.compareTo(t.key);
            if (cmp < 0)
                t = t.left;
            else if (cmp > 0)
                t = t.right;
            else
                return t.setValue(value);
        } while (t != null);
    }
    // 创建新节点并插入到合适位置
    Entry<K,V> e = new Entry<>(key, value, parent);
    if (cmp < 0)
        parent.left = e;
    else
        parent.right = e;
    // 调用fixAfterInsertion维护红黑树的平衡
    fixAfterInsertion(e);
    size++;
    modCount++;
    return null;
}

// java.util.TreeMap
private void fixAfterInsertion(Entry<K,V> x) {
    // 将新插入的节点设为红色
    x.color = RED;
    // 当 x 不是根节点，且 x 的父节点是红色时（违反规则4），需要循环修复
    while (x != null && x != root && x.parent.color == RED) {
        // 判断父节点是祖父节点的左孩子还是右孩子
        if (parentOf(x) == leftOf(parentOf(parentOf(x)))) {
            Entry<K,V> y = rightOf(parentOf(parentOf(x))); // y 是叔节点
            // 如果叔节点是红色
            if (colorOf(y) == RED) {
                setColor(parentOf(x), BLACK); // 父节点变黑
                setColor(y, BLACK); // 叔节点变黑
                setColor(parentOf(parentOf(x)), RED); // 祖父节点变红
                x = parentOf(parentOf(x)); // 指针上移，以祖父为当前节点继续循环
            } else {
                // 如果叔节点是黑色，且当前节点是右孩子
                if (x == rightOf(parentOf(x))) {
                    x = parentOf(x);  // 左旋（以父节点为中心）
                    rotateLeft(x);
                }
                // 叔节点是黑色，且当前节点是左孩子
                setColor(parentOf(x), BLACK); // 父节点变黑
                setColor(parentOf(parentOf(x)), RED); // 祖父节点变红
                rotateRight(parentOf(parentOf(x))); // 右旋（以祖父节点为中心）
            }
        } else {
            // 父节点是祖父的右孩子，逻辑同上，只是左右互换（镜像情况）
            Entry<K,V> y = leftOf(parentOf(parentOf(x)));
            if (colorOf(y) == RED) {
                setColor(parentOf(x), BLACK);
                setColor(y, BLACK);
                setColor(parentOf(parentOf(x)), RED);
                x = parentOf(parentOf(x));
            } else {
                if (x == leftOf(parentOf(x))) {
                    x = parentOf(x);
                    rotateRight(x);
                }
                setColor(parentOf(x), BLACK);
                setColor(parentOf(parentOf(x)), RED);
                rotateLeft(parentOf(parentOf(x)));
            }    
        }
    }
     // 确保根节点始终是黑色（符合规则2：根节点是黑色）
    root.color = BLACK;
}

// java.util.TreeSet
public Iterator<E> iterator() {
    return m.navigableKeySet().iterator();
}

// java.util.TreeMap
final class KeyIterator extends PrivateEntryIterator<K> {
    KeyIterator(Entry<K,V> first) {
        super(first);
    }
    public K next() {
        return nextEntry().key;
    }
}

final Entry<K,V> nextEntry() {
    Entry<K,V> e = next;
    if (e == null)
        throw new NoSuchElementException();
    // 预先计算下一个节点，保存在 next 变量中
    // 这里的算法是：如果当前节点有右子树，下一个节点是右子树的最左节点；
    // 如果没有右子树，下一个节点是第一个“祖先”节点，该节点的左子树包含当前节点。
    if ((next = successor(e)) == null)
        next = null;
    lastReturned = e;
    return e;
}
// 寻找后继节点的算法
static <K,V> TreeMap.Entry<K,V> successor(Entry<K,V> t) {
    if (t == null)
        return null;
    else if (t.right != null) {
        //  有右子树：找右子树中最左边的节点（最小的）
        Entry<K,V> p = t.right;
        while (p.left != null)
            p = p.left;
        return p;
    } else {
        //  无右子树：向上找第一个左拐的父节点
        Entry<K,V> p = t.parent;
        Entry<K,V> ch = t;
        while (p != null && ch == p.right) {
            ch = p;
            p = p.parent;
        }
        return p;
    }
}

// java.util.TreeSet
public E floor(E e) {
    return m.floorKey(e);
}
public K floorKey(K key) {
    Entry<K,V> p = getFloorEntry(key);
    return (p == null) ? null : p.key;
}
// 核心：寻找小于等于 key 的最大节点
final Entry<K,V> getFloorEntry(K key) {
    Entry<K,V> p = root;
    while (p != null) {
        int cmp = compare(key, p.key);
        if (cmp > 0) { // key > p.key
            if (p.right != null)
                p = p.right; // 往右找更大的
            else
                return p; // 没右了，当前 p 就是小于 key 的最大值
        } else if (cmp < 0) { // key < p.key
            if (p.left != null)
                p = p.left; // 往左找更小的
            else {
                // 没左了，说明当前 p 太大了，得往回找父节点
                Entry<K,V> parent = p.parent;
                Entry<K,V> ch = p;
                while (parent != null && ch == parent.left) {
                    ch = parent;
                    parent = parent.parent;
                }
                return parent;
            }
        } else
            return p; // 相等，直接返回
    }
    return null;
}

public NavigableSet<E> subSet(E fromElement, boolean fromInclusive,
                             E toElement, boolean toInclusive) {
    return new TreeSet<>(m.subMap(fromElement, fromInclusive,
                                  toElement, toInclusive));
}

public class ArrayDeque<E> extends AbstractCollection<E>
                           implements Deque<E>, Cloneable, Serializable
{
    // 用于存储元素的 
    transient Object[] elements;
    // 对头指针：指向队首元素
    transient int head;
    // 队尾指针：指向下一个待插入元素的位置（队尾元素的下一个位置）
    transient int tail;
    // 最小初始容量
    private static final int MIN_INITIAL_CAPACITY = 8;
}

// java.util.ArrayDeque
// 对头入队
public void addFirst(E e){
    // 安全检查: ArrayDeque 不允许 null
    if (e == null)
        throw new NullPointerException();
    // 元素入队，head 指针向前移动一位
    elements[head = (head - 1) & (elements.length - 1)] = e;
    // 在插入元素后，检查 head 是否追上了 tail
    // 在 ArrayDeque 中，数组中始终至少留一个空位
    // 当 head == tail 时，说明数组已经满了，没有空位了
    if (head == tail)
        doubleCapacity();
}
// 队尾入队
public void addLast(E e){
    // 安全检查: ArrayDeque 不允许 null
    if (e == null)
        throw new NullPointerException();
    // 元素入队，放在 tail 指向的位置
    elements[tail] = e;
    // tail 指针后移并判断是否需要扩容
    // (tail + 1) & (elements.length - 1) 等同于 (tail + 1) % length
    // 如果移动后的 tail 撞上了 head，说明数组已经满了
    if ( (tail = (tail + 1) & (elements.length - 1)) == head)
        doubleCapacity();
}

// java.util.ArrayDeque
// 删除队列头部元素
public E removeFirst() {
    // 调用 pollFirst() 方法尝试获取并移除队列头部的元素，并将结果赋值给变量 x
    E x = pollFirst();
    // 如果 pollFirst() 返回 null（意味着队列为空），则抛出一个 NoSuchElementException 异常
    if(x == null)
        throw new NoSuchElementException();
    // （队列不为空）返回获取到的元素 x
    return x;
}
public E pollFirst() {
    // 将当前队列头部的索引 head 赋值给局部变量 h
    int h = head;
    // @SuppressWarnings("unchecked") 用于抑制编译器的“未检查类型转换”警告
    // elements 数组是 Object[] 类型，将其中的元素强制转换为泛型 E 类型时，编译器会发出警告
    // 这里开发人员确认这种转换是安全的，因此忽略警告 
    @SuppressWarnings("unchecked")
    // 取出数组中索引为 h 的元素，并强制转换为泛型 E 类型，赋值给 result
    E result = (E) elements[h];
    // 判断取出的元素是否为 null
    if (result == null)
        return null;
    // 将原头部位置的数组元素显式设为 null
    // 手动置为 null，防止内存泄漏
    // 在 Java 中，只要一个对象被引用，垃圾回收器（GC）就不会回收它
    // 虽然我们即将把 head 指针移走，但数组中该位置仍然引用着旧的对象
    // 如不手动置为 null，这个对象可能一直占用内存直到数组被覆盖或回收
    elements[h] = null;
    // 计算新的头部索引
    head = (h + 1) & (elements.length - 1);
    // 返回之前取出的元素
    return result;
}
// 删除队列尾部元素
public E removeLast() {
    // 调用 pollLast() 方法尝试获取并移除队列尾部的元素，并将结果赋值给变量 x
    E x = pollLast();
    // 如果 pollLast() 返回 null（意味着队列为空），则抛出一个 NoSuchElementException 异常
    if(x == null)
        throw new NoSuchElementException();
    // （队列不为空）返回获取到的元素 x
    return x;
}
public E pollLast() {
    // 计算队尾元素索引
    // tail 指向下一个可用元素的位置（即当前队尾元素的下一位）
    // 实际的最后一个元素索引是 tail - 1
    int t = (tail - 1) & (elements.length - 1);
    @SuppressWarnings("unchecked")
    // 取出数组中索引为 t 的元素，并强制转换为泛型 E 类型，赋值给 result
    E result = (E) elements[t];
    // 判断取出的元素是否为 null
    if (result == null)
        return null;
    // 显式置空，帮助 GC
    elements[t] = null;
    // 将队尾指针 tail 移动到刚才取出元素的位置
    tail = t;
    // 返回取出的元素
    return result;
}

// java.util.ArrayDeque
private void doubleCapacity() {
    // 断言 head 等于 tail
    // 在循环数组中，当队列满时，head 和 tail 会指向同一个位置
    // （即下一个要插入的位置会被覆盖，或者表示没有空间）
    // 这个断言确保该方法只在队列满时被调用
    assert head == tail;
    // 保存当前队首的索引位置到变量 p
    int p = head;
    // 获取旧数组的长度 n
    int n = elements.length;
    // 计算从 head (即 p) 到数组末尾的元素个数
    int r = n - p; 
    // 计算新容量，n 左移 1 位相当于 n * 2
    int newCapacity = n << 1;
    // 检查新容量是否溢出
    // 如果 n 已经非常大（接近 Integer.MAX_VALUE），n * 2 会变成负数（整数溢出）
    // 此时队列已经无法继续扩容，抛出异常
    if (newCapacity < 0)
        throw new IllegalStateException("Sorry, deque too big");
    // 创建一个容量为 newCapacity 的新数组 a
    Object[] a = new Object[newCapacity];
    // 复制 head 到数组末尾的部分 到 新数组的开头
    System.arraycopy(elements, p, a, 0, r);
    // 复制 数组开头 到 tail 的部分 到 新数组的后面
    System.arraycopy(elements, 0, a, r, p);
    // 将队列内部的数组引用指向新数组 a
    elements = a;
    // 重置队首 head 为新数组的 0 索引
    head = 0;
    // 重置队尾 tail 为旧数组的长度 n
    tail = n;
}

// java.util.ArrayDeque( doubleCapacity() )
int p = head;            // p = 4
int n = elements.length; // n = 8
int r = n - p;           // r = 8 - 4 = 4 (head右边有4个元素)
int newCapacity = n << 1; // newCapacity = 16
Object[] a = new Object[newCapacity]; // 创建新数组，长度 16
// 步骤 1: 复制右半部分 [A, B, C, D] 到新数组开头
System.arraycopy(elements, p, a, 0, r);
// 步骤 2: 复制左半部分 [E, F, G, H] 到新数组后面
System.arraycopy(elements, 0, a, r, p);
elements = a; // 引用指向新数组
head = 0;     // 重置 head
tail = n;     // 重置 tail = 8

import java.util.PriorityQueue;
public class priorityQueueDemo {
    public static void main(String[] args) {
        PriorityQueue<Integer> queue = new PriorityQueue<>();
        // 乱序插入
        queue.add(3);
        queue.add(1);
        queue.add(2);
        queue.add(5);
        queue.add(4);
        // 验证“内部无序”：直接打印集合
        System.out.println("直接打印内部结构(无序): " + queue);
        // 输出可能是: [1, 2, 3, 5, 4]  <-- 注意这不是完全排序，只是堆结构
        // 验证“出队有序”：使用 poll 遍历
        System.out.print("依次出队(有序): ");
        while (!queue.isEmpty()) {
            System.out.println(queue.poll());
        }
        // 输出: 1 2 3 4 5
    }
}

// java.util
public class PriorityQueue<E> extends AbstractQueue<E>
    implements java.io.Serializable {
    // 默认初始容量
    private static final int DEFAULT_INITIAL_CAPACITY = 11;
    // 底层存储数组：通过二叉堆的逻辑来维护这个数组
    transient Object[] queue;
    // 当前元素个数
    private int size = 0;
    // 比较器：如果为 null，则使用自然排序
    private final Comparator<? super E> comparator;
    // 修改次数（用于 fail-fast 机制）
    transient int modCount = 0;
}

// java.util.PriorityQueue
public boolean add(E e) {
    return offer(e);
}
public boolean offer(E e) {
    // 非空检查
    // PriorityQueue 不允许插入 null 元素，如果插入 null 抛出异常
    if(e == null)
        throw new NullPointerException();
    // 修改计数器更新
    modCount++;
    // 获取当前队列的大小 i
    int i = size;
    // 如果当前元素数量 i 已经大于或等于底层数组 queue 的长度，说明数组已满
    if (i >= queue.length)
        // 调用 grow(i + 1) 方法进行扩容，以确保能容纳新元素
        grow(i + 1);
    // 更新队列大小 i
    size = i + 1;
    // 如果插入前队列是空的（i == 0），直接将元素放在数组的第一个位置 queue[0]
    if (i == 0)
        queue[0] = e;
    // 如果队列不为空，调用 siftUp(i, e) 方法，执行上浮调整
    else
        siftUp(i, e);
    return true;
}

// java.util.PriorityQueue
private void siftUp(int k,E x) {
    if (comparator != null)
        siftUpUsingComparator(k, x);
    else
        siftUpComparable(k, x);
}
private void siftUpUsingComparator(int k,E x) {
    // 循环条件：while (k > 0)
    // 只要当前节点索引 k 不是根节点（根节点索引为 0），就继续尝试上浮
    while (k > 0) {
        // 计算当前节点的父节点索引
        int parent = (k - 1) >>> 1;
        // 取出父节点存储的元素
        Object e = queue[parent];
        // 使用比较器比较当前待插入元素 x 和父节点元素 e
        // 如果 x 大于或等于 e，则 break 跳出循环。此时位置 k 就是 x 的最终归宿
        if (comparator.compare(x, (E) e) >= 0)
            break;
        // 如果 x 小于 e，说明违反了堆序性质（子节点比父节点小），需要交换位置。
        queue[k] = e;
        // 更新当前索引 k 为父节点的索引，准备继续向上层比较
        k = parent;
    }
    // 循环结束后（要么找到了合适的位置，要么到了根节点），将目标元素 key 放入最终确定的位置 k
    queue[k] = x;
}
private void siftUpComparable(int k,E x) {
    // 将传入的元素 x 强制转换为 Comparable 类型
    // PriorityQueue 需要比较元素的大小来确定优先级
    Comparable<? super E> key = (Comparable<? super E>) x;
    // 开始循环。只要当前节点索引 k 大于 0（即当前节点不是根节点），就继续尝试上浮
    while (k > 0) {
        // 计算当前节点的父节点索引
        int parent = (k - 1) >>> 1;
        // 取出父节点存储的元素
        Object e = queue[parent];
        // 比较当前插入元素 key 和父节点元素 e 的大小
        // 如果 key >= e
        // 说明堆的性质已经满足（父节点小于等于子节点），无需继续交换，直接 break 跳出循环
        if (key.compareTo((E) e) >= 0)
            break;
        // 如果 key < e，说明子节点比父节点小，违反了最小堆性质
        // 则将父节点 e 向下移动到当前子节点 k 的位置
        queue[k] = e;
        // 更新当前索引 k 为父节点的索引，准备继续向上层比较
        k = parent;
    } 
    // 循环结束后（要么找到了合适的位置，要么到了根节点），将目标元素 key 放入最终确定的位置 k
    queue[k] = key;
}

// java.util.PriorityQueue
public E poll() {
    // 检查队列是否为空
    if (size == 0)
        return null; // 如果为空，返回 null（区别于 remove() 方法抛出异常）
    // 记录操作前的元素个数，并将 size 减 1
    // s 变成了原数组最后一个元素的下标
    int s = --size;
    // 更新修改计数器
    modCount++;
    // 获取堆顶元素（即最小值），作为最终要返回的结果
    E result = (E) queue[0];
    // 获取队列末尾的元素
    E x = (E) queue[s];
    // 将原末尾位置置为 null，帮助 GC 回收，避免内存泄漏
    queue[s] = null;
    // 如果队列中不止一个元素，则需要执行下沉操作
    // 将刚才取出的末尾元素 x 放到堆顶位置（下标 0），并开始下沉
    if (s != 0)
        siftDown(0, x);
    // 返回之前获取的最小值
    return result;
}

// java.util.PriorityQueue
private void siftDown(int k, E x) {
    if (comparator != null)
        siftDownUsingComparator(k, x);
    else
        siftDownComparable(k, x);
}
private void siftDownUsingComparator(int k, E x) {
    // 计算非叶子节点边界
    int half = size >>> 1; // 无符号右移（等同于 size / 2）
    while (k < half) {
        // 计算当前节点 k 的左孩子的索引
        int child = (k << 1) + 1;
        // 获取左孩子元素 
        Object c = queue[child];
        // 计算右孩子的索引
        int right = child + 1;
        // 如果右孩子存在，且右孩子比左孩子小
        if (right < size &&
                comparator.compare((E) c, (E) queue[right]) > 0)
            c = queue[child = right]; // 更新 child 指向右孩子
        // 如果当前元素 x 已经小于等于较小的孩子，说明下沉结束
        if (comparator.compare(x, (E) c) <= 0)
            break;
        // 否则，交换位置（孩子上浮成为父节点）
        queue[k] = c;
        k = child;
    }
    // 将末尾元素放到最终的位置
    queue[k] = x;
}
private void siftDownComparable(int k, E x) {
    // 将待下沉的元素 x 强制转换为 Comparable 接口类型
    // 因为需要调用 compareTo 方法来比较元素大小
    Comparable<? super E> key = (Comparable<? super E>)x;
    // 计算非叶子节点边界
    int half = size >>> 1; // 无符号右移（等同于 size / 2）
    while (k < half) {
        // 计算当前节点 k 的左孩子的索引
        int child = (k << 1) + 1;
        // 获取左孩子元素
        Object c = queue[child];
        // 计算右孩子的索引
        int right = child + 1;
        // 比较左右孩子
        // right<size：检查右孩子是否存在（是否越界）
        // c.compareTo(queue[right])>0：如果左孩子比右孩子大（compareTo 返回正数）说明右孩子更小
        if (right < size &&
                ((Comparable<? super E>) c).compareTo((E) queue[right]) > 0)
            // 满足条件，将 c 指向右孩子，并将 child 更新为右孩子的索引
            c = queue[child = right];
        // 如果 key 小于等于 c（compareTo 返回 0 或负数），说明堆的顺序已经正确（父节点小于子节点）
        if (key.compareTo((E) c) <= 0)
            // 跳出循环，下沉结束
            break;
        // 如果 key 大于 c，说明堆性质被破坏。将较小的子节点 c 移动到当前父节点 k 的位置
        queue[k] = c;
        // 更新 k 为子节点的位置，准备进行下一轮比较
        k = child;
    }
    // 循环结束后，将原始元素 key 放到最终确定的位置 k 上
    queue[k] = key;
}

// java.util.PriorityQueue
private void grow(int minCapacity) {
    // 获取当前底层数组 queue 的长度
    int oldCapacity = queue.length;
    // 如果旧容量小于 64，则扩容 2 倍 + 2
    // 如果旧容量大于 64，则扩容 1.5 倍 (即 oldCapacity + (oldCapacity >> 1))
    int newCapacity = oldCapacity + ((oldCapacity < 64) ?
                                         (oldCapacity + 2) :
                                         (oldCapacity >> 1));
    // 防止溢出，如果计算出的容量过大
    if (newCapacity - MAX_ARRAY_SIZE > 0)
        // 调用 hugeCapacity 方法尝试分配
        newCapacity = hugeCapacity(minCapacity);
    // 调用 Arrays.copyOf 方法，将原数组中的数据复制到一个长度为 newCapacity 的新数组中，并将 queue 引用指向这个新数组
    queue = Arrays.copyOf(queue, newCapacity);  
}
private static int hugeCapacity(int minCapacity) {
    // 溢出检查：通过检查 minCapacity 是否小于 0，来判断是否发生了整数溢出
    // 在 Java 中，int 是有符号的 32 位整数，最大值为 Integer.MAX_VALUE（约 21 亿）
    // 如果之前的计算（例如 minCapacity = oldCapacity + (oldCapacity >> 1)）导致数值超过了 int 的最大值
    // 由于整数溢出，结果会变成负数
    if (minCapacity < 0)
        throw new OutOfMemoryError();
    // 如果 minCapacity 大于 MAX_ARRAY_SIZE，则直接返回 Integer.MAX_VALUE（即 2147483647）尝试分配理论上的最大数组长度
    // 如果 minCapacity 小于或等于 MAX_ARRAY_SIZE，则返回 MAX_ARRAY_SIZE（Integer.MAX_VALUE - 8（即 2147483639））
    return (minCapacity > MAX_ARRAY_SIZE) ?
            Integer.MAX_VALUE :
            MAX_ARRAY_SIZE;
}