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 // Android-changed: href changed in javadoc for redirection. 34 /** 35 * Implementing this interface allows an object to be the target of 36 * the "for-each loop" statement. See 37 * <strong> 38 * <a href="https://docs.oracle.com/javase/8/docs/technotes/guides/language/foreach.html">For-each Loop</a> 39 * </strong> 40 * 41 * @param <T> the type of elements returned by the iterator 42 * 43 * @since 1.5 44 * @jls 14.14.2 The enhanced for statement 45 */ 46 public interface Iterable<T> { 47 /** 48 * Returns an iterator over elements of type {@code T}. 49 * 50 * @return an Iterator. 51 */ iterator()52 Iterator<T> iterator(); 53 54 /** 55 * Performs the given action for each element of the {@code Iterable} 56 * until all elements have been processed or the action throws an 57 * exception. Unless otherwise specified by the implementing class, 58 * actions are performed in the order of iteration (if an iteration order 59 * is specified). Exceptions thrown by the action are relayed to the 60 * caller. 61 * 62 * @implSpec 63 * <p>The default implementation behaves as if: 64 * <pre>{@code 65 * for (T t : this) 66 * action.accept(t); 67 * }</pre> 68 * 69 * @param action The action to be performed for each element 70 * @throws NullPointerException if the specified action is null 71 * @since 1.8 72 */ forEach(Consumer<? super T> action)73 default void forEach(Consumer<? super T> action) { 74 Objects.requireNonNull(action); 75 for (T t : this) { 76 action.accept(t); 77 } 78 } 79 80 /** 81 * Creates a {@link Spliterator} over the elements described by this 82 * {@code Iterable}. 83 * 84 * @implSpec 85 * The default implementation creates an 86 * <em><a href="Spliterator.html#binding">early-binding</a></em> 87 * spliterator from the iterable's {@code Iterator}. The spliterator 88 * inherits the <em>fail-fast</em> properties of the iterable's iterator. 89 * 90 * @implNote 91 * The default implementation should usually be overridden. The 92 * spliterator returned by the default implementation has poor splitting 93 * capabilities, is unsized, and does not report any spliterator 94 * characteristics. Implementing classes can nearly always provide a 95 * better implementation. 96 * 97 * @return a {@code Spliterator} over the elements described by this 98 * {@code Iterable}. 99 * @since 1.8 100 */ spliterator()101 default Spliterator<T> spliterator() { 102 return Spliterators.spliteratorUnknownSize(iterator(), 0); 103 } 104 } 105