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 @SuppressWarnings("overloads") 95 public static interface OfInt extends PrimitiveIterator<Integer, IntConsumer> { 96 97 /** 98 * Returns the next {@code int} element in the iteration. 99 * 100 * @return the next {@code int} element in the iteration 101 * @throws NoSuchElementException if the iteration has no more elements 102 */ nextInt()103 int nextInt(); 104 105 /** 106 * {@inheritDoc} 107 * @implSpec 108 * <p>The default implementation behaves as if: 109 * <pre>{@code 110 * while (hasNext()) 111 * action.accept(nextInt()); 112 * }</pre> 113 */ forEachRemaining(IntConsumer action)114 default void forEachRemaining(IntConsumer action) { 115 Objects.requireNonNull(action); 116 while (hasNext()) 117 action.accept(nextInt()); 118 } 119 120 /** 121 * {@inheritDoc} 122 * @implSpec 123 * The default implementation boxes the result of calling 124 * {@link #nextInt()}, and returns that boxed result. 125 */ 126 @Override next()127 default Integer next() { 128 if (Tripwire.ENABLED) 129 Tripwire.trip(getClass(), "{0} calling PrimitiveIterator.OfInt.nextInt()"); 130 return nextInt(); 131 } 132 133 /** 134 * {@inheritDoc} 135 * @implSpec 136 * If the action is an instance of {@code IntConsumer} then it is cast 137 * to {@code IntConsumer} and passed to {@link #forEachRemaining}; 138 * otherwise the action is adapted to an instance of 139 * {@code IntConsumer}, by boxing the argument of {@code IntConsumer}, 140 * and then passed to {@link #forEachRemaining}. 141 */ 142 @Override forEachRemaining(Consumer<? super Integer> action)143 default void forEachRemaining(Consumer<? super Integer> action) { 144 if (action instanceof IntConsumer) { 145 forEachRemaining((IntConsumer) action); 146 } 147 else { 148 // The method reference action::accept is never null 149 Objects.requireNonNull(action); 150 if (Tripwire.ENABLED) 151 Tripwire.trip(getClass(), "{0} calling PrimitiveIterator.OfInt.forEachRemainingInt(action::accept)"); 152 forEachRemaining((IntConsumer) action::accept); 153 } 154 } 155 156 } 157 158 /** 159 * An Iterator specialized for {@code long} values. 160 * @since 1.8 161 */ 162 @SuppressWarnings("overloads") 163 public static interface OfLong extends PrimitiveIterator<Long, LongConsumer> { 164 165 /** 166 * Returns the next {@code long} element in the iteration. 167 * 168 * @return the next {@code long} element in the iteration 169 * @throws NoSuchElementException if the iteration has no more elements 170 */ nextLong()171 long nextLong(); 172 173 /** 174 * {@inheritDoc} 175 * @implSpec 176 * <p>The default implementation behaves as if: 177 * <pre>{@code 178 * while (hasNext()) 179 * action.accept(nextLong()); 180 * }</pre> 181 */ forEachRemaining(LongConsumer action)182 default void forEachRemaining(LongConsumer action) { 183 Objects.requireNonNull(action); 184 while (hasNext()) 185 action.accept(nextLong()); 186 } 187 188 /** 189 * {@inheritDoc} 190 * @implSpec 191 * The default implementation boxes the result of calling 192 * {@link #nextLong()}, and returns that boxed result. 193 */ 194 @Override next()195 default Long next() { 196 if (Tripwire.ENABLED) 197 Tripwire.trip(getClass(), "{0} calling PrimitiveIterator.OfLong.nextLong()"); 198 return nextLong(); 199 } 200 201 /** 202 * {@inheritDoc} 203 * @implSpec 204 * If the action is an instance of {@code LongConsumer} then it is cast 205 * to {@code LongConsumer} and passed to {@link #forEachRemaining}; 206 * otherwise the action is adapted to an instance of 207 * {@code LongConsumer}, by boxing the argument of {@code LongConsumer}, 208 * and then passed to {@link #forEachRemaining}. 209 */ 210 @Override forEachRemaining(Consumer<? super Long> action)211 default void forEachRemaining(Consumer<? super Long> action) { 212 if (action instanceof LongConsumer) { 213 forEachRemaining((LongConsumer) action); 214 } 215 else { 216 // The method reference action::accept is never null 217 Objects.requireNonNull(action); 218 if (Tripwire.ENABLED) 219 Tripwire.trip(getClass(), "{0} calling PrimitiveIterator.OfLong.forEachRemainingLong(action::accept)"); 220 forEachRemaining((LongConsumer) action::accept); 221 } 222 } 223 } 224 225 /** 226 * An Iterator specialized for {@code double} values. 227 * @since 1.8 228 */ 229 @SuppressWarnings("overloads") 230 public static interface OfDouble extends PrimitiveIterator<Double, DoubleConsumer> { 231 232 /** 233 * Returns the next {@code double} element in the iteration. 234 * 235 * @return the next {@code double} element in the iteration 236 * @throws NoSuchElementException if the iteration has no more elements 237 */ nextDouble()238 double nextDouble(); 239 240 /** 241 * {@inheritDoc} 242 * @implSpec 243 * <p>The default implementation behaves as if: 244 * <pre>{@code 245 * while (hasNext()) 246 * action.accept(nextDouble()); 247 * }</pre> 248 */ forEachRemaining(DoubleConsumer action)249 default void forEachRemaining(DoubleConsumer action) { 250 Objects.requireNonNull(action); 251 while (hasNext()) 252 action.accept(nextDouble()); 253 } 254 255 /** 256 * {@inheritDoc} 257 * @implSpec 258 * The default implementation boxes the result of calling 259 * {@link #nextDouble()}, and returns that boxed result. 260 */ 261 @Override next()262 default Double next() { 263 if (Tripwire.ENABLED) 264 Tripwire.trip(getClass(), "{0} calling PrimitiveIterator.OfDouble.nextLong()"); 265 return nextDouble(); 266 } 267 268 /** 269 * {@inheritDoc} 270 * @implSpec 271 * If the action is an instance of {@code DoubleConsumer} then it is 272 * cast to {@code DoubleConsumer} and passed to 273 * {@link #forEachRemaining}; otherwise the action is adapted to 274 * an instance of {@code DoubleConsumer}, by boxing the argument of 275 * {@code DoubleConsumer}, and then passed to 276 * {@link #forEachRemaining}. 277 */ 278 @Override forEachRemaining(Consumer<? super Double> action)279 default void forEachRemaining(Consumer<? super Double> action) { 280 if (action instanceof DoubleConsumer) { 281 forEachRemaining((DoubleConsumer) action); 282 } 283 else { 284 // The method reference action::accept is never null 285 Objects.requireNonNull(action); 286 if (Tripwire.ENABLED) 287 Tripwire.trip(getClass(), "{0} calling PrimitiveIterator.OfDouble.forEachRemainingDouble(action::accept)"); 288 forEachRemaining((DoubleConsumer) action::accept); 289 } 290 } 291 } 292 } 293