| /* | |
| * Copyright (c) 2013, 2025, 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; | |
| import java.util.function.DoubleConsumer; | |
| import java.util.function.IntConsumer; | |
| import java.util.function.LongConsumer; | |
| /** | |
| * A base type for primitive specializations of {@code Iterator}. Specialized | |
| * subtypes are provided for {@link OfInt int}, {@link OfLong long}, and | |
| * {@link OfDouble double} values. | |
| * | |
| * <p>The specialized subtype default implementations of {@link Iterator#next} | |
| * and {@link Iterator#forEachRemaining(java.util.function.Consumer)} box | |
| * primitive values to instances of their corresponding wrapper class. Such | |
| * boxing may offset any advantages gained when using the primitive | |
| * specializations. To avoid boxing, the corresponding primitive-based methods | |
| * should be used. For example, {@link PrimitiveIterator.OfInt#nextInt()} and | |
| * {@link PrimitiveIterator.OfInt#forEachRemaining(java.util.function.IntConsumer)} | |
| * should be used in preference to {@link PrimitiveIterator.OfInt#next()} and | |
| * {@link PrimitiveIterator.OfInt#forEachRemaining(java.util.function.Consumer)}. | |
| * | |
| * <p>Iteration of primitive values using boxing-based methods | |
| * {@link Iterator#next next()} and | |
| * {@link Iterator#forEachRemaining(java.util.function.Consumer) forEachRemaining()}, | |
| * does not affect the order in which the values, transformed to boxed values, | |
| * are encountered. | |
| * | |
| * @implNote | |
| * If the boolean system property {@code org.openjdk.java.util.stream.tripwire} | |
| * is set to {@code true} then diagnostic warnings are reported if boxing of | |
| * primitive values occur when operating on primitive subtype specializations. | |
| * | |
| * @param <T> the type of elements returned by this PrimitiveIterator. The | |
| * type must be a wrapper type for a primitive type, such as | |
| * {@code Integer} for the primitive {@code int} type. | |
| * @param <T_CONS> the type of primitive consumer. The type must be a | |
| * primitive specialization of {@link java.util.function.Consumer} for | |
| * {@code T}, such as {@link java.util.function.IntConsumer} for | |
| * {@code Integer}. | |
| * | |
| * @since 1.8 | |
| */ | |
| public interface PrimitiveIterator<T, T_CONS> extends Iterator<T> { | |
| /** | |
| * 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. | |
| * <p> | |
| * The behavior of an iterator is unspecified if the action modifies the | |
| * source of elements in any way (even by calling the {@link #remove remove} | |
| * method or other mutator methods of {@code Iterator} subtypes), | |
| * unless an overriding class has specified a concurrent modification policy. | |
| * <p> | |
| * Subsequent behavior of an iterator is unspecified if the action throws an | |
| * exception. | |
| * | |
| * @param action The action to be performed for each element | |
| * @throws NullPointerException if the specified action is null | |
| */ | |
| void forEachRemaining(T_CONS action); | |
| /** | |
| * An Iterator specialized for {@code int} values. | |
| * @since 1.8 | |
| */ | |
| @SuppressWarnings("overloads") | |
| public static interface OfInt extends PrimitiveIterator<Integer, IntConsumer> { | |
| /** | |
| * Returns the next {@code int} element in the iteration. | |
| * | |
| * @return the next {@code int} element in the iteration | |
| * @throws NoSuchElementException if the iteration has no more elements | |
| */ | |
| int nextInt(); | |
| /** | |
| * {@inheritDoc} | |
| * @implSpec | |
| * <p>The default implementation behaves as if: | |
| * <pre>{@code | |
| * while (hasNext()) | |
| * action.accept(nextInt()); | |
| * }</pre> | |
| */ | |
| default void forEachRemaining(IntConsumer action) { | |
| Objects.requireNonNull(action); | |
| while (hasNext()) | |
| action.accept(nextInt()); | |
| } | |
| /** | |
| * {@inheritDoc} | |
| * @implSpec | |
| * The default implementation boxes the result of calling | |
| * {@link #nextInt()}, and returns that boxed result. | |
| */ | |
| @Override | |
| default Integer next() { | |
| if (Tripwire.ENABLED) | |
| Tripwire.trip(getClass(), "{0} calling PrimitiveIterator.OfInt.nextInt()"); | |
| return nextInt(); | |
| } | |
| /** | |
| * {@inheritDoc} | |
| * @implSpec | |
| * If the action is an instance of {@code IntConsumer} then it is cast | |
| * to {@code IntConsumer} and passed to {@link #forEachRemaining}; | |
| * otherwise the action is adapted to an instance of | |
| * {@code IntConsumer}, by boxing the argument of {@code IntConsumer}, | |
| * and then passed to {@link #forEachRemaining}. | |
| */ | |
| @Override | |
| default void forEachRemaining(Consumer<? super Integer> action) { | |
| if (action instanceof IntConsumer) { | |
| forEachRemaining((IntConsumer) action); | |
| } | |
| else { | |
| // The method reference action::accept is never null | |
| Objects.requireNonNull(action); | |
| if (Tripwire.ENABLED) | |
| Tripwire.trip(getClass(), "{0} calling PrimitiveIterator.OfInt.forEachRemainingInt(action::accept)"); | |
| forEachRemaining((IntConsumer) action::accept); | |
| } | |
| } | |
| } | |
| /** | |
| * An Iterator specialized for {@code long} values. | |
| * @since 1.8 | |
| */ | |
| @SuppressWarnings("overloads") | |
| public static interface OfLong extends PrimitiveIterator<Long, LongConsumer> { | |
| /** | |
| * Returns the next {@code long} element in the iteration. | |
| * | |
| * @return the next {@code long} element in the iteration | |
| * @throws NoSuchElementException if the iteration has no more elements | |
| */ | |
| long nextLong(); | |
| /** | |
| * {@inheritDoc} | |
| * @implSpec | |
| * <p>The default implementation behaves as if: | |
| * <pre>{@code | |
| * while (hasNext()) | |
| * action.accept(nextLong()); | |
| * }</pre> | |
| */ | |
| default void forEachRemaining(LongConsumer action) { | |
| Objects.requireNonNull(action); | |
| while (hasNext()) | |
| action.accept(nextLong()); | |
| } | |
| /** | |
| * {@inheritDoc} | |
| * @implSpec | |
| * The default implementation boxes the result of calling | |
| * {@link #nextLong()}, and returns that boxed result. | |
| */ | |
| @Override | |
| default Long next() { | |
| if (Tripwire.ENABLED) | |
| Tripwire.trip(getClass(), "{0} calling PrimitiveIterator.OfLong.nextLong()"); | |
| return nextLong(); | |
| } | |
| /** | |
| * {@inheritDoc} | |
| * @implSpec | |
| * If the action is an instance of {@code LongConsumer} then it is cast | |
| * to {@code LongConsumer} and passed to {@link #forEachRemaining}; | |
| * otherwise the action is adapted to an instance of | |
| * {@code LongConsumer}, by boxing the argument of {@code LongConsumer}, | |
| * and then passed to {@link #forEachRemaining}. | |
| */ | |
| @Override | |
| default void forEachRemaining(Consumer<? super Long> action) { | |
| if (action instanceof LongConsumer) { | |
| forEachRemaining((LongConsumer) action); | |
| } | |
| else { | |
| // The method reference action::accept is never null | |
| Objects.requireNonNull(action); | |
| if (Tripwire.ENABLED) | |
| Tripwire.trip(getClass(), "{0} calling PrimitiveIterator.OfLong.forEachRemainingLong(action::accept)"); | |
| forEachRemaining((LongConsumer) action::accept); | |
| } | |
| } | |
| } | |
| /** | |
| * An Iterator specialized for {@code double} values. | |
| * @since 1.8 | |
| */ | |
| @SuppressWarnings("overloads") | |
| public static interface OfDouble extends PrimitiveIterator<Double, DoubleConsumer> { | |
| /** | |
| * Returns the next {@code double} element in the iteration. | |
| * | |
| * @return the next {@code double} element in the iteration | |
| * @throws NoSuchElementException if the iteration has no more elements | |
| */ | |
| double nextDouble(); | |
| /** | |
| * {@inheritDoc} | |
| * @implSpec | |
| * <p>The default implementation behaves as if: | |
| * <pre>{@code | |
| * while (hasNext()) | |
| * action.accept(nextDouble()); | |
| * }</pre> | |
| */ | |
| default void forEachRemaining(DoubleConsumer action) { | |
| Objects.requireNonNull(action); | |
| while (hasNext()) | |
| action.accept(nextDouble()); | |
| } | |
| /** | |
| * {@inheritDoc} | |
| * @implSpec | |
| * The default implementation boxes the result of calling | |
| * {@link #nextDouble()}, and returns that boxed result. | |
| */ | |
| @Override | |
| default Double next() { | |
| if (Tripwire.ENABLED) | |
| Tripwire.trip(getClass(), "{0} calling PrimitiveIterator.OfDouble.nextLong()"); | |
| return nextDouble(); | |
| } | |
| /** | |
| * {@inheritDoc} | |
| * @implSpec | |
| * If the action is an instance of {@code DoubleConsumer} then it is | |
| * cast to {@code DoubleConsumer} and passed to | |
| * {@link #forEachRemaining}; otherwise the action is adapted to | |
| * an instance of {@code DoubleConsumer}, by boxing the argument of | |
| * {@code DoubleConsumer}, and then passed to | |
| * {@link #forEachRemaining}. | |
| */ | |
| @Override | |
| default void forEachRemaining(Consumer<? super Double> action) { | |
| if (action instanceof DoubleConsumer) { | |
| forEachRemaining((DoubleConsumer) action); | |
| } | |
| else { | |
| // The method reference action::accept is never null | |
| Objects.requireNonNull(action); | |
| if (Tripwire.ENABLED) | |
| Tripwire.trip(getClass(), "{0} calling PrimitiveIterator.OfDouble.forEachRemainingDouble(action::accept)"); | |
| forEachRemaining((DoubleConsumer) action::accept); | |
| } | |
| } | |
| } | |
| } |