1 /*
2  * Copyright (c) 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.util;
26 
27 import java.util.function.Consumer;
28 import java.util.function.DoubleConsumer;
29 import java.util.function.IntConsumer;
30 import java.util.function.LongConsumer;
31 
32 /**
33  * A base type for primitive specializations of {@code Iterator}.  Specialized
34  * subtypes are provided for {@link OfInt int}, {@link OfLong long}, and
35  * {@link OfDouble double} values.
36  *
37  * <p>The specialized subtype default implementations of {@link Iterator#next}
38  * and {@link Iterator#forEachRemaining(java.util.function.Consumer)} box
39  * primitive values to instances of their corresponding wrapper class.  Such
40  * boxing may offset any advantages gained when using the primitive
41  * specializations.  To avoid boxing, the corresponding primitive-based methods
42  * should be used.  For example, {@link PrimitiveIterator.OfInt#nextInt()} and
43  * {@link PrimitiveIterator.OfInt#forEachRemaining(java.util.function.IntConsumer)}
44  * should be used in preference to {@link PrimitiveIterator.OfInt#next()} and
45  * {@link PrimitiveIterator.OfInt#forEachRemaining(java.util.function.Consumer)}.
46  *
47  * <p>Iteration of primitive values using boxing-based methods
48  * {@link Iterator#next next()} and
49  * {@link Iterator#forEachRemaining(java.util.function.Consumer) forEachRemaining()},
50  * does not affect the order in which the values, transformed to boxed values,
51  * are encountered.
52  *
53  * @implNote
54  * If the boolean system property {@code org.openjdk.java.util.stream.tripwire}
55  * is set to {@code true} then diagnostic warnings are reported if boxing of
56  * primitive values occur when operating on primitive subtype specializations.
57  *
58  * @param <T> the type of elements returned by this PrimitiveIterator.  The
59  *        type must be a wrapper type for a primitive type, such as
60  *        {@code Integer} for the primitive {@code int} type.
61  * @param <T_CONS> the type of primitive consumer.  The type must be a
62  *        primitive specialization of {@link java.util.function.Consumer} for
63  *        {@code T}, such as {@link java.util.function.IntConsumer} for
64  *        {@code Integer}.
65  *
66  * @since 1.8
67  */
68 public interface PrimitiveIterator<T, T_CONS> extends Iterator<T> {
69 
70     /**
71      * Performs the given action for each remaining element until all elements
72      * have been processed or the action throws an exception.  Actions are
73      * performed in the order of iteration, if that order is specified.
74      * Exceptions thrown by the action are relayed to the caller.
75      * <p>
76      * The behavior of an iterator is unspecified if the action modifies the
77      * source of elements in any way (even by calling the {@link #remove remove}
78      * method or other mutator methods of {@code Iterator} subtypes),
79      * unless an overriding class has specified a concurrent modification policy.
80      * <p>
81      * Subsequent behavior of an iterator is unspecified if the action throws an
82      * exception.
83      *
84      * @param action The action to be performed for each element
85      * @throws NullPointerException if the specified action is null
86      */
87     @SuppressWarnings("overloads")
forEachRemaining(T_CONS action)88     void forEachRemaining(T_CONS action);
89 
90     /**
91      * An Iterator specialized for {@code int} values.
92      * @since 1.8
93      */
94     public static interface OfInt extends PrimitiveIterator<Integer, IntConsumer> {
95 
96         /**
97          * Returns the next {@code int} element in the iteration.
98          *
99          * @return the next {@code int} element in the iteration
100          * @throws NoSuchElementException if the iteration has no more elements
101          */
nextInt()102         int nextInt();
103 
104         /**
105          * {@inheritDoc}
106          * @implSpec
107          * <p>The default implementation behaves as if:
108          * <pre>{@code
109          *     while (hasNext())
110          *         action.accept(nextInt());
111          * }</pre>
112          */
forEachRemaining(IntConsumer action)113         default void forEachRemaining(IntConsumer action) {
114             Objects.requireNonNull(action);
115             while (hasNext())
116                 action.accept(nextInt());
117         }
118 
119         /**
120          * {@inheritDoc}
121          * @implSpec
122          * The default implementation boxes the result of calling
123          * {@link #nextInt()}, and returns that boxed result.
124          */
125         @Override
next()126         default Integer next() {
127             if (Tripwire.ENABLED)
128                 Tripwire.trip(getClass(), "{0} calling PrimitiveIterator.OfInt.nextInt()");
129             return nextInt();
130         }
131 
132         /**
133          * {@inheritDoc}
134          * @implSpec
135          * If the action is an instance of {@code IntConsumer} then it is cast
136          * to {@code IntConsumer} and passed to {@link #forEachRemaining};
137          * otherwise the action is adapted to an instance of
138          * {@code IntConsumer}, by boxing the argument of {@code IntConsumer},
139          * and then passed to {@link #forEachRemaining}.
140          */
141         @Override
forEachRemaining(Consumer<? super Integer> action)142         default void forEachRemaining(Consumer<? super Integer> action) {
143             if (action instanceof IntConsumer) {
144                 forEachRemaining((IntConsumer) action);
145             }
146             else {
147                 // The method reference action::accept is never null
148                 Objects.requireNonNull(action);
149                 if (Tripwire.ENABLED)
150                     Tripwire.trip(getClass(), "{0} calling PrimitiveIterator.OfInt.forEachRemainingInt(action::accept)");
151                 forEachRemaining((IntConsumer) action::accept);
152             }
153         }
154 
155     }
156 
157     /**
158      * An Iterator specialized for {@code long} values.
159      * @since 1.8
160      */
161     public static interface OfLong extends PrimitiveIterator<Long, LongConsumer> {
162 
163         /**
164          * Returns the next {@code long} element in the iteration.
165          *
166          * @return the next {@code long} element in the iteration
167          * @throws NoSuchElementException if the iteration has no more elements
168          */
nextLong()169         long nextLong();
170 
171         /**
172          * {@inheritDoc}
173          * @implSpec
174          * <p>The default implementation behaves as if:
175          * <pre>{@code
176          *     while (hasNext())
177          *         action.accept(nextLong());
178          * }</pre>
179          */
forEachRemaining(LongConsumer action)180         default void forEachRemaining(LongConsumer action) {
181             Objects.requireNonNull(action);
182             while (hasNext())
183                 action.accept(nextLong());
184         }
185 
186         /**
187          * {@inheritDoc}
188          * @implSpec
189          * The default implementation boxes the result of calling
190          * {@link #nextLong()}, and returns that boxed result.
191          */
192         @Override
next()193         default Long next() {
194             if (Tripwire.ENABLED)
195                 Tripwire.trip(getClass(), "{0} calling PrimitiveIterator.OfLong.nextLong()");
196             return nextLong();
197         }
198 
199         /**
200          * {@inheritDoc}
201          * @implSpec
202          * If the action is an instance of {@code LongConsumer} then it is cast
203          * to {@code LongConsumer} and passed to {@link #forEachRemaining};
204          * otherwise the action is adapted to an instance of
205          * {@code LongConsumer}, by boxing the argument of {@code LongConsumer},
206          * and then passed to {@link #forEachRemaining}.
207          */
208         @Override
forEachRemaining(Consumer<? super Long> action)209         default void forEachRemaining(Consumer<? super Long> action) {
210             if (action instanceof LongConsumer) {
211                 forEachRemaining((LongConsumer) action);
212             }
213             else {
214                 // The method reference action::accept is never null
215                 Objects.requireNonNull(action);
216                 if (Tripwire.ENABLED)
217                     Tripwire.trip(getClass(), "{0} calling PrimitiveIterator.OfLong.forEachRemainingLong(action::accept)");
218                 forEachRemaining((LongConsumer) action::accept);
219             }
220         }
221     }
222 
223     /**
224      * An Iterator specialized for {@code double} values.
225      * @since 1.8
226      */
227     public static interface OfDouble extends PrimitiveIterator<Double, DoubleConsumer> {
228 
229         /**
230          * Returns the next {@code double} element in the iteration.
231          *
232          * @return the next {@code double} element in the iteration
233          * @throws NoSuchElementException if the iteration has no more elements
234          */
nextDouble()235         double nextDouble();
236 
237         /**
238          * {@inheritDoc}
239          * @implSpec
240          * <p>The default implementation behaves as if:
241          * <pre>{@code
242          *     while (hasNext())
243          *         action.accept(nextDouble());
244          * }</pre>
245          */
forEachRemaining(DoubleConsumer action)246         default void forEachRemaining(DoubleConsumer action) {
247             Objects.requireNonNull(action);
248             while (hasNext())
249                 action.accept(nextDouble());
250         }
251 
252         /**
253          * {@inheritDoc}
254          * @implSpec
255          * The default implementation boxes the result of calling
256          * {@link #nextDouble()}, and returns that boxed result.
257          */
258         @Override
next()259         default Double next() {
260             if (Tripwire.ENABLED)
261                 Tripwire.trip(getClass(), "{0} calling PrimitiveIterator.OfDouble.nextLong()");
262             return nextDouble();
263         }
264 
265         /**
266          * {@inheritDoc}
267          * @implSpec
268          * If the action is an instance of {@code DoubleConsumer} then it is
269          * cast to {@code DoubleConsumer} and passed to
270          * {@link #forEachRemaining}; otherwise the action is adapted to
271          * an instance of {@code DoubleConsumer}, by boxing the argument of
272          * {@code DoubleConsumer}, and then passed to
273          * {@link #forEachRemaining}.
274          */
275         @Override
forEachRemaining(Consumer<? super Double> action)276         default void forEachRemaining(Consumer<? super Double> action) {
277             if (action instanceof DoubleConsumer) {
278                 forEachRemaining((DoubleConsumer) action);
279             }
280             else {
281                 // The method reference action::accept is never null
282                 Objects.requireNonNull(action);
283                 if (Tripwire.ENABLED)
284                     Tripwire.trip(getClass(), "{0} calling PrimitiveIterator.OfDouble.forEachRemainingDouble(action::accept)");
285                 forEachRemaining((DoubleConsumer) action::accept);
286             }
287         }
288     }
289 }
290