Java基础系列（四十六）：Set & AbstractSet

/**
 * 返回 set 中的元素个数
 * @return  set中元素个数
 */
int size();

/**
 * 如果set中不包含任何元素，返回true
 * @return  如果set中不包含任何元素，返回true
 */
boolean isEmpty();

/**
 * 如果set包含指定的元素，则返回 true
 * @param o 指定的元素
 * @return  如果 set 包含指定的元素，则返回 true。
 */
boolean contains(Object o);

/**
 * 如果此 set 包含指定 collection 的所有元素，则返回 true。
 * 如果指定的 collection 也是一个 set，那么当该 collection 是此 set 的 子集 时返回 true。
 * @param c 检查是否包含在此 set 中的 collection
 * @return 如果此 set 包含指定 collection 中的所有元素，则返回 true
 */
boolean containsAll(Collection<?> c);

/**
 * 如果 set 中尚未存在指定的元素，则添加此元素
 * @param e 被添加的元素
 * @return  如果set中存在该元素，添加失败并返回false
 */
boolean add(E e);

/**
 * 如果 set 中没有指定 collection 中的所有元素，则将其添加到此 set 中
 * 如果指定的 collection 也是一个 set，则 addAll 操作会实际修改此 set，
 * 这样其值是两个 set 的一个 并集。如果操作正在进行的同时修改了指定的 collection，则此操作的行为是不确定的。
 * @param c
 * @return
 */
boolean addAll(Collection<? extends E> c);

/**
 * 如果 set 中存在指定的元素，则将其移除（可选操作）。
 * @param o 被删除的元素
 * @return  如果此 set 包含指定的对象，则返回true
 */
boolean remove(Object o);

/**
 * 仅保留 set 中那些包含在指定 collection 中的元素，换句话说，只取两者交集，其余的不管
 * @param c 与set进行判断的集合
 * @return  如果此 set 由于调用而发生更改，则返回 true
 */
boolean retainAll(Collection<?> c);


/**
 * 移除 set 中那些包含在指定 collection 中的元素，也就是说，取交集之外的所有元素
 * @param c 与set进行判断的集合
 * @return  如果此 set 由于调用而发生更改，则返回 true
 */
boolean removeAll(Collection<?> c);


/**
 * 移除此 set 中的所有元素，此调用返回后该 set 将是空的。
 */
void clear();

/**
 * 可切割的迭代器，返回的是该set集合的可切割迭代器的一个实例
 * @return
 */
@Override
default Spliterator<E> spliterator() {
    return Spliterators.spliterator(this, Spliterator.DISTINCT);
}

/**
 * 比较指定对象与此 set 的相等性。如果给定对象也是一个 set，
 * 两个 set 的大小相等，并且给定 set 的每个成员都包含在此 set 中，则返回 true。
 * 这确保 equals 方法在 Set 接口的不同实现间正常工作。
 * @param o 被比较的元素
 * @return  如果相等返回true
 */
@Override
public boolean equals(Object o) {
    if (o == this) {
        return true;
    }
    if (!(o instanceof Set)) {
        return false;
    }
    Collection<?> c = (Collection<?>) o;
    if (c.size() != size()) {
        return false;
    }
    try {
        return containsAll(c);
    } catch (ClassCastException unused)   {
        return false;
    } catch (NullPointerException unused) {
        return false;
    }
}


/**
 * 返回此 set 的哈希码值。set 的哈希码被定义为该 set 中元素的哈希码的总和，其中 null 元素的哈希码被定义为 0。
 * 这确保了 s1.equals(s2) 意味着对于任何两个 set s1 和 s2，都有 s1.hashCode()==s2.hashCode()。
 * @return
 */
@Override
public int hashCode() {
    int h = 0;
    Iterator<E> i = iterator();
    while (i.hasNext()) {
        E obj = i.next();
        if (obj != null) {
            h += obj.hashCode();
        }
    }
    return h;
}

/**
 * 从此 set 中移除包含在指定 collection 中的所有元素
 * 如果指定 collection 也是一个 set，则此操作有效地修改此 set，从而其值成为两个 set 的 不对称差集。
 *
 * @param c 包含将从此 set 中移除的元素的 collection
 * @return 如果此 set 由于调用而发生更改，则返回 true
 */
@Override
public boolean removeAll(Collection<?> c) {
    Objects.requireNonNull(c);
    boolean modified = false;
    //通过在此 set 和指定 collection 上调用 size 方法，此实现可以确定哪一个更小。
    if (size() > c.size()) {
        // 如果此 set 中的元素更少，则该实现将在此 set 上进行迭代，依次检查迭代器返回的每个元素，查看它是否包含在指定的 collection 中。
        for (Iterator<?> i = c.iterator(); i.hasNext(); ) {
            //如果包含它，则使用迭代器的 remove 方法从此 set 中将其移除。
            modified |= remove(i.next());
        }
    } else {
        //如果指定 collection 中的元素更少，则该实现将在指定的 collection 上进行迭代，并使用此 set 的 remove 方法，从此 set 中移除迭代器返回的每个元素。
        for (Iterator<?> i = iterator(); i.hasNext(); ) {
            if (c.contains(i.next())) {
                i.remove();
                modified = true;
            }
        }
    }
    return modified;
}