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 */ 25 package java.lang; 26 27 import java.util.Iterator; 28 import java.util.Objects; 29 import java.util.Spliterator; 30 import java.util.Spliterators; 31 import java.util.function.Consumer; 32 33 /** 34 * Implementing this interface allows an object to be the target of the enhanced 35 * {@code for} statement (sometimes called the "for-each loop" statement). 36 * 37 * @param <T> the type of elements returned by the iterator 38 * 39 * @since 1.5 40 * @jls 14.14.2 The enhanced {@code for} statement 41 */ 42 public interface Iterable<T> { 43 /** 44 * Returns an iterator over elements of type {@code T}. 45 * 46 * @return an Iterator. 47 */ iterator()48 Iterator<T> iterator(); 49 50 /** 51 * Performs the given action for each element of the {@code Iterable} 52 * until all elements have been processed or the action throws an 53 * exception. Actions are performed in the order of iteration, if that 54 * order is specified. Exceptions thrown by the action are relayed to the 55 * caller. 56 * <p> 57 * The behavior of this method is unspecified if the action performs 58 * side-effects that modify the underlying source of elements, unless an 59 * overriding class has specified a concurrent modification policy. 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 */ forEach(Consumer<? super T> action)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="../util/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 */ spliterator()100 default Spliterator<T> spliterator() { 101 return Spliterators.spliteratorUnknownSize(iterator(), 0); 102 } 103 } 104