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 javany.lang; 26 27 import javany.util.Iterator; 28 import java.util.Objects; 29 //import java.util.Spliterator; 30 //import java.util.Spliterators; 31 import javany.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}/../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 */ 45 public interface Iterable<any 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 Iterator<T> iterator = iterator(); 78 while (iterator.hasNext()) { 79 action.accept(iterator.next()); 80 } 81 } 82 83 /** 84 * Creates a {@link Spliterator} over the elements described by this 85 * {@code Iterable}. 86 * 87 * @implSpec 88 * The default implementation creates an 89 * <em><a href="../util/Spliterator.html#binding">early-binding</a></em> 90 * spliterator from the iterable's {@code Iterator}. The spliterator 91 * inherits the <em>fail-fast</em> properties of the iterable's iterator. 92 * 93 * @implNote 94 * The default implementation should usually be overridden. The 95 * spliterator returned by the default implementation has poor splitting 96 * capabilities, is unsized, and does not report any spliterator 97 * characteristics. Implementing classes can nearly always provide a 98 * better implementation. 99 * 100 * @return a {@code Spliterator} over the elements described by this 101 * {@code Iterable}. 102 * @since 1.8 103 */ 104 // default Spliterator<T> spliterator() { 105 // return Spliterators.spliteratorUnknownSize(iterator(), 0); 106 // } 107 }