Iterable

package java.lang;

import java.util.Iterator;
import java.util.Objects;
import java.util.Spliterator;
import java.util.Spliterators;
import java.util.function.Consumer;

/**
 * 实现这个接口的对象可以作为"for-each"语句的循环目标. 查看
 * <strong>
 * <a href="{@docRoot}/../technotes/guides/language/foreach.html">For-each Loop</a>
 * </strong>
 *
 * @param <T> 迭代器将返回此类型的元素
 *
 * @since 1.5
 * @jls 14.14.2 增强的for语句
 */
public interface Iterable<T> {
    /**
     * 返回元素类型为{@code T}的迭代器.
     *
     * @return 一个Iterator.
     */
    Iterator<T> iterator();

    /**
     * 对{@code Iterable}的每个元素执行给与的action，直到全部元素
     * 处理完成或action抛出了一个异常。除非实现类制定了不同的方
     * 式，否则action将按照迭代顺序执行(如果指定了迭代顺序)。
     * 并在异常传递到action的调用者时抛出异常
     *
     * @implSpec
     * <p>默认实现的行为像是这样:
     * <pre>{@code
     *     for (T t : this)
     *         action.accept(t);
     * }</pre>
     *
     * @param action 这个action将随每一个元素被调用
     * @throws NullPointerException 如果指定的action参数为空时
     * @since 1.8
     */
    default void forEach(Consumer<? super T> action) {
        Objects.requireNonNull(action);
        for (T t : this) {
            action.accept(t);
        }
    }

    /**
     * 使用{@code Iterable}对象创建{@link Spliterator}
     *
     * @implSpec
     * 使用可迭代的迭代器创建一个<em><a href="Spliterator.html#binding">early-binding</a></em>
     * spliterator对象.  这个spliterator对象从迭代器中继承了<em>快速失败</em>特性
     *
     * @implNote
     * 这个默认的实现通常应该被重写，默认实现所返回的spliterator对象缺乏并
     * 发性、未知大小并且没有展示任何sqlisterator特性。实现类通常总会提供很好的实现。
     *
     * @return 一个使用当前对象声明的 {@code Spliterator}对象
     * @since 1.8
     */
    default Spliterator<T> spliterator() {
        return Spliterators.spliteratorUnknownSize(iterator(), 0);
    }