Java 数据结构 -- 18.Java 8 数据结构补充介绍 EnumSet

前言

书接上文，上一篇对 TreeMap 进行了介绍与分析，对于 Java 大部分经典数据结构都已介绍完毕，本篇将对 EnumSet 进行介绍与分析。

在阅读 EnumSet 源码的时候发现它的部分实现是在子类中完成，所以不上 EnumSet 的继承关系图。

/**
 * 一个为了与枚举类型一起使用的特殊性的 {@link Set} 实现类。所有 enum set 的元素必须来自同一个指定的枚
 * 举类型，显式的或者隐式的，在 set 被创建的时候。Enum sets 内部被当作 bit vectors 代表。这种表示法是
 * 特别坚实和高效的。这个类的空间和时间的性能应该足够好来允许它当作传统的基于 int 的 “bit flags” 的一个
 * 高质量的，类型安全的选项，如果例如 containsAll 和 retainAll 的参数也是一个 enum set，那么即使是扩
 * 展操作也应该会运行的非常快。
 *
 * iterator 方法返回的迭代器以它们的自然顺序横穿元素s（enum 常数被定义的顺序）。返回的爹地爱情是弱一直
 * 的：它永远不会抛出 {@link ConcurrentModificationException} 并可它可能或者不可能对于在迭代操作过
 * 程中的修改操作显式任何影响。
 * 
 * Null 元素s是不被允许的。试图插入一个 null 元素将抛出 {@link NullPointerException}。但是试图测试
 * 或者移除一个 null 元素将，正常调用。
 *
 * 就像大部分 collection 的实现类s，EnumSet 不是线程安全的。如果多个线程并行访问了一个 enum set，它应
 * 该从外部实现线程安全。这通常是通过在一些实现了线程安全的的对象中自然封装这个 enum set 来实现的。如果不
 * 存在这样的对象，这个 set 应该使用 {@link Collections#synchronizedSet} 方法"包装"。这最好在创建
 * 的时候完成，来防止意外的线程不安全的访问：
 *
 * <pre>
 * Set<MyEnum> s = Collections.synchronizedSet(EnumSet.noneOf(MyEnum.class));
 * </pre>
 *
 * 实现类注意：所有继承操作都在一个常数时间内执行。它们看上去（虽然没有保证）比它们对应的 {@link 
 * HashSet} 对象更快。如果它们的参数也是一个 enum set，那么即使是扩展操作s执也将在常数时间内执行完。
 *
 * EnumSet 类继承自 AbstractSet 抽象类，实现了 Cloneable 接口与 Serializable 接口
 */
public abstract class EnumSet<E extends Enum<E>> extends AbstractSet<E>
    implements Cloneable, java.io.Serializable
{
   
    /**
     * 所有当前 set 的元素的类
     */
    final Class<E> elementType;

    /**
     * 所有包含 T 的值。（为了性能缓存。）
     */
    final Enum<?>[] universe;

    private static Enum<?>[] ZERO_LENGTH_ENUM_ARRAY = new Enum<?>[0];

		//带参构造器，一个元素类参数，一个枚举类型对象数组
    EnumSet(Class<E>elementType, Enum<?>[] universe) {
   
    		//为两个类属性赋初值
        this.elementType = elementType;
        this.universe    = universe;
    }

    /**
     * 使用指定的元素类型创建一个空的 enum set。这个方法是 EnumSet 实现重要方法，虽然它本身是一个 
     * static 方法，但是每次调用都会返回一个新的对象。
     */
    public static <E extends Enum<E>> EnumSet<E> noneOf(Class<E> elementType) {
   
        Enum<?>[] universe = getUniverse(elementType); //#getUniverse，获取枚举类型的所有实例
        if (universe == null)
            throw new ClassCastException(elementType + " not an enum");

        if (universe.length <= 64) //如果 universe 的长度小于等于 64，这也是一种类似于 HashMap 中的决定 plain node 或者 tree node 的策略模式
            return new RegularEnumSet<>(elementType, universe); //调用 RegularEnumSet 构造器
        else
            return new JumboEnumSet<>(elementType, universe); //如果 universe 的长度大于 64，调用 JumboEnumSet 构造器
    }

    /**
     * 创建一个包含指定的元素类型的所有元素的 enum set。
     */
    public static <E extends Enum<E>> EnumSet<E> allOf(Class<E> elementType) {
   
        EnumSet<E> result = noneOf(elementType); //#noneOf 
        result.addAll(); //调用 result 的 addAll 方法
        return result;
    }

    /**
     * 从适当的枚举类型中添加所有元素到这个 enum set 中，它调用调用之前是空的。这个方法必须由子类实现，
     * 这里就可以看出 RegularEnumSet 与 JumboEnumSet 在 addAll 的实现上是不同的。
     */
    abstract void addAll();

    /**
     * 创建一个与指定 enum set 拥有相同元素类型的 enum set，使用与它（指定 enum set） 相同的所有元素
     * （如果有的话）初始化。
     */
    public static <E extends Enum<E>> EnumSet<E> copyOf(EnumSet<E> s) {
   
        return s.clone(); //调用参数的 clone 方法
    }

    /**
     * 从指定 collection 创建一个被初始化的 enum set。如果指定 collection 是一个 EnumSet 实例，这
     * 个静态工厂方法与 {@link #copyOf(EnumSet)} 行为相同。否则的话，指定 collection 必须包含至少
     * 一个元素（为了定义新 enum set 的元素类型）。
     */
    public static <E extends Enum<E>> EnumSet<E> copyOf(Collection<E> c) {
   
        if (c instanceof EnumSet) {
    //如果参数是 EnumSet 实例
            return ((EnumSet<E>)c).clone(); //调用 c.clone 方法
        } else {
    //如果参数不是 EnumSet 实例
            if (c.isEmpty()) 
                throw new IllegalArgumentException("Collection is empty");
            Iterator<E> i = c.iterator(); //获取参数的迭代器
            E first = i.next(); //获取游标下一个元素（第一个元素） 
            EnumSet<E> result = EnumSet.of(first); //调用 EnumSet#of 缓存一个 EnumSet 对象
            while (i.hasNext()) //循环如果游标之后还有与元素
                result.add(i.next()); //步移加入 result
            return result; //返回 result
        }
    }

    /**
     * 创建一个与指定 enum set 元素类型相同的 enum set，使用所有指定 set 中不包含类型的元素来初始化。
     */
    public static <E extends Enum<E>> EnumSet<E> complementOf(EnumSet<E> s) {
   
        EnumSet<E> result = copyOf(s); //#copyOf
        result.complement(); //调用 result.complement
        return result; //返回 result
    }

    /**
     * 创建一个被指定元素的初始化的 enum set。
     *
     * 存在这个方法的重载方法s使用一到五个元素来初始化一个 enum set。一个第六个参数的重载方法使用可变参
     * 数功能实现。这个重载方法可以被用来建立一个包含任意数量元素的 enum set，但是看上去比不使用可变参数
     * 的重载方法s更慢。单参版本
     */
    public static <E extends Enum<E>> EnumSet<E> of(E e) {
   
        EnumSet<E> result = noneOf(e.getDeclaringClass()); //#noneOf
        result.add(e); //调用 result.add
        return result; //返回 result
    }

    /**
     * 双参版本
     */
    public static <E extends Enum<E>> EnumSet<E> of(E e1, E e2) {
   
        EnumSet<E> result = noneOf(e1.getDeclaringClass()); //#noneOf
        result.add(e1);  //调用两次 add
        result.add(e2);
        return result;
    }

    /**
     * 三参版本
     */
    public static <E extends Enum<E>> EnumSet<E> of(E e1, E e2, E e3) {
   
        EnumSet<E> result = noneOf(e1.getDeclaringClass()); //#noneOf
        result.add(e1); //调用三次 add
        result.add(e2);
        result.add(e3);
        return result;
    }

    /**
     * 四参版本
     */
    public static <E extends Enum<E>> EnumSet<E> of(E e1, E e2, E e3, E e4) {
   
        EnumSet<E> result = noneOf(e1.getDeclaringClass()); //#noneOf
        result.add(e1); //调用四次 add
        result.add(e2);
        result.add(e3);
        result.add(e4);
        return result;
    }

    /**
     * 五参版本
     */
    public static <E extends Enum<E>> EnumSet<E> of(E e1, E e2, E e3, E e4,
                                                    E e5)
    {
   
        EnumSet<E> result = noneOf(e1.getDeclaringClass()); //#noneOf
        result.add(e1); //调用五次 add
        result.add(e2);
        result.add(e3);
        result.add(e4);
        result.add(e5);
        return result;
    }

    /**
     * 变长版本
     */
    @SafeVarargs
    public static <E extends Enum<E>> EnumSet<E> of(E first, E... rest) {
   
        EnumSet<E> result = noneOf(first.getDeclaringClass()); //#noneOf
        result.add(first);
        for (E e : rest) //通过 for 循环调用 add
            result.