1/*
2 * Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation.  Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25package java.lang;
26
27import java.util.Iterator;
28import java.util.Objects;
29import java.util.Spliterator;
30import java.util.Spliterators;
31import java.util.function.Consumer;
32
33/**
34 * Implementing this interface allows an object to be the target of
35 * the "for-each loop" statement. See
36 * <strong>
37 * <a href="{@docRoot}openjdk-redirect.html?v=8&path=/technotes/guides/language/foreach.html">For-each Loop</a>
38 * </strong>
39 *
40 * @param <T> the type of elements returned by the iterator
41 *
42 * @since 1.5
43 * @jls 14.14.2 The enhanced for statement
44 */
45public interface Iterable<T> {
46    /**
47     * Returns an iterator over elements of type {@code T}.
48     *
49     * @return an Iterator.
50     */
51    Iterator<T> iterator();
52
53    /**
54     * Performs the given action for each element of the {@code Iterable}
55     * until all elements have been processed or the action throws an
56     * exception.  Unless otherwise specified by the implementing class,
57     * actions are performed in the order of iteration (if an iteration order
58     * is specified).  Exceptions thrown by the action are relayed to the
59     * caller.
60     *
61     * @implSpec
62     * <p>The default implementation behaves as if:
63     * <pre>{@code
64     *     for (T t : this)
65     *         action.accept(t);
66     * }</pre>
67     *
68     * @param action The action to be performed for each element
69     * @throws NullPointerException if the specified action is null
70     * @since 1.8
71     */
72    default void forEach(Consumer<? super T> action) {
73        Objects.requireNonNull(action);
74        for (T t : this) {
75            action.accept(t);
76        }
77    }
78
79    /**
80     * Creates a {@link Spliterator} over the elements described by this
81     * {@code Iterable}.
82     *
83     * @implSpec
84     * The default implementation creates an
85     * <em><a href="Spliterator.html#binding">early-binding</a></em>
86     * spliterator from the iterable's {@code Iterator}.  The spliterator
87     * inherits the <em>fail-fast</em> properties of the iterable's iterator.
88     *
89     * @implNote
90     * The default implementation should usually be overridden.  The
91     * spliterator returned by the default implementation has poor splitting
92     * capabilities, is unsized, and does not report any spliterator
93     * characteristics. Implementing classes can nearly always provide a
94     * better implementation.
95     *
96     * @return a {@code Spliterator} over the elements described by this
97     * {@code Iterable}.
98     * @since 1.8
99     */
100    default Spliterator<T> spliterator() {
101        return Spliterators.spliteratorUnknownSize(iterator(), 0);
102    }
103}
104