| /* |
| * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved. |
| * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
| * |
| * This code is free software; you can redistribute it and/or modify it |
| * under the terms of the GNU General Public License version 2 only, as |
| * published by the Free Software Foundation. Oracle designates this |
| * particular file as subject to the "Classpath" exception as provided |
| * by Oracle in the LICENSE file that accompanied this code. |
| * |
| * This code is distributed in the hope that it will be useful, but WITHOUT |
| * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
| * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
| * version 2 for more details (a copy is included in the LICENSE file that |
| * accompanied this code). |
| * |
| * You should have received a copy of the GNU General Public License version |
| * 2 along with this work; if not, write to the Free Software Foundation, |
| * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
| * |
| * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
| * or visit www.oracle.com if you need additional information or have any |
| * questions. |
| */ |
| |
| package java.util; |
| |
| import java.util.function.Consumer; |
| |
| /** |
| * An iterator over a collection. {@code Iterator} takes the place of |
| * {@link Enumeration} in the Java Collections Framework. Iterators |
| * differ from enumerations in two ways: |
| * |
| * <ul> |
| * <li> Iterators allow the caller to remove elements from the |
| * underlying collection during the iteration with well-defined |
| * semantics. |
| * <li> Method names have been improved. |
| * </ul> |
| * |
| * <p>This interface is a member of the |
| * <a href="https://docs.oracle.com/javase/8/docs/technotes/guides/collections/index.html"> |
| * Java Collections Framework</a>. |
| * |
| * @param <E> the type of elements returned by this iterator |
| * |
| * @author Josh Bloch |
| * @see Collection |
| * @see ListIterator |
| * @see Iterable |
| * @since 1.2 |
| */ |
| public interface Iterator<E> { |
| /** |
| * Returns {@code true} if the iteration has more elements. |
| * (In other words, returns {@code true} if {@link #next} would |
| * return an element rather than throwing an exception.) |
| * |
| * @return {@code true} if the iteration has more elements |
| */ |
| boolean hasNext(); |
| |
| /** |
| * Returns the next element in the iteration. |
| * |
| * @return the next element in the iteration |
| * @throws NoSuchElementException if the iteration has no more elements |
| */ |
| E next(); |
| |
| /** |
| * Removes from the underlying collection the last element returned |
| * by this iterator (optional operation). This method can be called |
| * only once per call to {@link #next}. The behavior of an iterator |
| * is unspecified if the underlying collection is modified while the |
| * iteration is in progress in any way other than by calling this |
| * method. |
| * |
| * @implSpec |
| * The default implementation throws an instance of |
| * {@link UnsupportedOperationException} and performs no other action. |
| * |
| * @throws UnsupportedOperationException if the {@code remove} |
| * operation is not supported by this iterator |
| * |
| * @throws IllegalStateException if the {@code next} method has not |
| * yet been called, or the {@code remove} method has already |
| * been called after the last call to the {@code next} |
| * method |
| */ |
| default void remove() { |
| throw new UnsupportedOperationException("remove"); |
| } |
| |
| /** |
| * Performs the given action for each remaining element until all elements |
| * have been processed or the action throws an exception. Actions are |
| * performed in the order of iteration, if that order is specified. |
| * Exceptions thrown by the action are relayed to the caller. |
| * |
| * @implSpec |
| * <p>The default implementation behaves as if: |
| * <pre>{@code |
| * while (hasNext()) |
| * action.accept(next()); |
| * }</pre> |
| * |
| * @param action The action to be performed for each element |
| * @throws NullPointerException if the specified action is null |
| * @since 1.8 |
| */ |
| default void forEachRemaining(Consumer<? super E> action) { |
| Objects.requireNonNull(action); |
| while (hasNext()) |
| action.accept(next()); |
| } |
| } |