package java.lang;

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

/**
 * 實現(xiàn)這個接口的對象可以作為"for-each"語句的循環(huán)目標. 查看
 * <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}的每個元素執(zhí)行給與的action，直到全部元素
     * 處理完成或action拋出了一個異常。除非實現(xiàn)類制定了不同的方
     * 式，否則action將按照迭代順序執(zhí)行(如果指定了迭代順序)。
     * 并在異常傳遞到action的調(diào)用者時拋出異常
     *
     * @implSpec
     * <p>默認實現(xiàn)的行為像是這樣:
     * <pre>{@code
     *     for (T t : this)
     *         action.accept(t);
     * }</pre>
     *
     * @param action 這個action將隨每一個元素被調(diào)用
     * @throws NullPointerException 如果指定的action參數(shù)為空時
     * @since 1.8
     */
    default void forEach(Consumer<? super T> action) {
        Objects.requireNonNull(action);
        for (T t : this) {
            action.accept(t);
        }
    }

    /**
     * 使用{@code Iterable}對象創(chuàng)建{@link Spliterator}
     *
     * @implSpec
     * 使用可迭代的迭代器創(chuàng)建一個<em><a href="Spliterator.html#binding">early-binding</a></em>
     * spliterator對象.  這個spliterator對象從迭代器中繼承了<em>快速失敗</em>特性
     *
     * @implNote
     * 這個默認的實現(xiàn)通常應(yīng)該被重寫，默認實現(xiàn)所返回的spliterator對象缺乏并
     * 發(fā)性、未知大小并且沒有展示任何sqlisterator特性。實現(xiàn)類通?？倳峁┖芎玫膶崿F(xiàn)。
     *
     * @return 一個使用當前對象聲明的 {@code Spliterator}對象
     * @since 1.8
     */
    default Spliterator<T> spliterator() {
        return Spliterators.spliteratorUnknownSize(iterator(), 0);
    }