Iterable

/**
 * Implementing this interface allows an object to be the target of
 * the "for-each loop" statement. See
 * <strong>
 * <a href="{@docRoot}/../technotes/guides/language/foreach.html">For-each Loop</a>
 * </strong>
 *
 * @param <T> the type of elements returned by the iterator
 *
 * @since 1.5
 * @jls 14.14.2 The enhanced for statement
 */
public interface Iterable<T> {
    /**
     * Returns an iterator over elements of type {@code T}.
     *
     * @return an Iterator.
     */
    Iterator<T> iterator();

    /**
     * Performs the given action for each element of the {@code Iterable}
     * until all elements have been processed or the action throws an
     * exception.  Unless otherwise specified by the implementing class,
     * actions are performed in the order of iteration (if an iteration order
     * is specified).  Exceptions thrown by the action are relayed to the
     * caller.
     *
     * @implSpec
     * <p>The default implementation behaves as if:
     * <pre>{@code
     *     for (T t : this)
     *         action.accept(t);
     * }</pre>
     *
     * @param action The action to be performed for each element
     * @throws NullPointerException if the specified action is null
     * @since 1.8
     */
    default void forEach(Consumer<? super T> action) {
        Objects.requireNonNull(action);
        for (T t : this) {
            action.accept(t);
        }
    }

    /**
     * Creates a {@link Spliterator} over the elements described by this
     * {@code Iterable}.
     *
     * @implSpec
     * The default implementation creates an
     * <em><a href="Spliterator.html#binding">early-binding</a></em>
     * spliterator from the iterable's {@code Iterator}.  The spliterator
     * inherits the <em>fail-fast</em> properties of the iterable's iterator.
     *
     * @implNote
     * The default implementation should usually be overridden.  The
     * spliterator returned by the default implementation has poor splitting
     * capabilities, is unsized, and does not report any spliterator
     * characteristics. Implementing classes can nearly always provide a
     * better implementation.
     *
     * @return a {@code Spliterator} over the elements described by this
     * {@code Iterable}.
     * @since 1.8
     */
    default Spliterator<T> spliterator() {
        return Spliterators.spliteratorUnknownSize(iterator(), 0);
    }
}

/**
 * 实现该接口允许对象成为“for-each循环”语句的目标
 *
 * @param <T> 迭代器返回的元素类型
 *
 * @since 1.5
 * @jls 14.14.2 增强型陈述
 */
public interface Iterable<T> {
    /**
     * 返回一个元素类型为T的迭代器
     *
     * @return 一个迭代器.
     */
    Iterator<T> iterator();

    /**
     * 对迭代器的每个元素执行给定的操作直到处理完所有元素或抛出异常。
     * 除非实现类另有规定，否则操作将按迭代顺序执行(如果指定了迭代顺序)。
     * 操作抛出的异常将被反馈给调用者。
     *
     * @implSpec 默认的实现形式如下：
     *     for (T t : this)
     *         action.accept(t);
     *
     * @param action 每个元素要执行的操作
     * @throws NullPointerException 如果指定的操作为空
     * @since 1.8
     */
    default void forEach(Consumer<? super T> action) {
        Objects.requireNonNull(action);
        for (T t : this) {
            action.accept(t);
        }
    }

    /**
     * 在迭代器描述的元素上创建一个并行遍历迭代器。
     *
     * @implSpec 
     * 默认实现会根据迭代器创建一个早期绑定的并行遍历迭代器。
     * 并行遍历迭代器继承了迭代器的快速失败属性。
     *
     * @implNote
     * 默认实现通常应该被重写。
     * 默认实现返回的分配器具有很差的拆分能力，不定大小，并且不报告任何分配器特性。 
     * 实现类几乎总是能够提供更好的实现。
     *
     * @return 该迭代器描述的元素上的一个并行遍历迭代器。
     * @since 1.8
     */
    default Spliterator<T> spliterator() {
        return Spliterators.spliteratorUnknownSize(iterator(), 0);
    }
}