Rhyme/Java Iterable接口源码解析

Java 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 loop”语句的目标。
 *
 * @param <T> 迭代器返回的元素的类型
 *
 * @since 1.5
 * @jls 14.14.2 增强的语句
 */
public interface Iterable<T> {

    /**
     * 
     * 返回类型为T的元素的迭代器
     * @return an Iterator.
     */
    Iterator<T> iterator();

     /**
     * 
     * 对Iterable的每个元素执行给定的动作
     * 直到所有的元素都被处理完毕或者动作引发异常。
     * 除非实现类另有规定，否则按迭代次序（如果指定迭代次序）执行操作。
     * 由操作抛出的异常被中继给调用者。
     * 
     * @implSpec
     * 默认实现的行为如下：
     * {
     *     for (T t : this)
     *         action.accept(t);
     * }
     *
     * @param action 要为每个元素执行的操作
     * @throws NullPointerException 如果指定的动作是空的
     * @since 1.8
     */
    default void forEach(Consumer<? super T> action) {
        //检查指定的action引用不是{null}。
        Objects.requireNonNull(action);
        for (T t : this) {
            //对给定的参数执行此操作。
            action.accept(t);
        }
    }
    /**
     * 在Iterable描述的元素上创建Spliterator。
     * Spliterator是一个用于遍历和分割源的元素的对象。
     * 由Spliterator覆盖的元素的源可以是例如数组，集合，IO通道或生成器函数。
     *
     * @implSpec
     * 他默认的实现是从iterable的Iterator中创建一个早期绑定的spliterator
     * spliterator继承了迭代器Iterator的失效快速属性。
     *  
     *
     * @implNote
     * 默认的实现通常应该被覆盖。 
     * 由默认实现返回的spliterator具有较差的分割能力，未分级，
     * 并且不报告任何spliterator特征。
     * 实现类几乎总能提供更好的实现。
     * 
     * @since 1.8
     */
    default Spliterator<T> spliterator() {
        return Spliterators.spliteratorUnknownSize(iterator(), 0);
    }
}