1 /*
   2  * Copyright (c) 2012, 2016, 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.stream;
  26 
  27 import java.util.Arrays;
  28 import java.util.IntSummaryStatistics;
  29 import java.util.Objects;
  30 import java.util.OptionalDouble;
  31 import java.util.OptionalInt;
  32 import java.util.PrimitiveIterator;
  33 import java.util.Spliterator;
  34 import java.util.Spliterators;
  35 import java.util.function.BiConsumer;
  36 import java.util.function.Function;
  37 import java.util.function.IntBinaryOperator;
  38 import java.util.function.IntConsumer;
  39 import java.util.function.IntFunction;
  40 import java.util.function.IntPredicate;
  41 import java.util.function.IntSupplier;
  42 import java.util.function.IntToDoubleFunction;
  43 import java.util.function.IntToLongFunction;
  44 import java.util.function.IntUnaryOperator;
  45 import java.util.function.ObjIntConsumer;
  46 import java.util.function.Supplier;
  47 
  48 /**
  49  * A sequence of primitive int-valued elements supporting sequential and parallel
  50  * aggregate operations.  This is the {@code int} primitive specialization of
  51  * {@link Stream}.
  52  *
  53  * <p>The following example illustrates an aggregate operation using
  54  * {@link Stream} and {@link IntStream}, computing the sum of the weights of the
  55  * red widgets:
  56  *
  57  * <pre>{@code
  58  *     int sum = widgets.stream()
  59  *                      .filter(w -> w.getColor() == RED)
  60  *                      .mapToInt(w -> w.getWeight())
  61  *                      .sum();
  62  * }</pre>
  63  *
  64  * See the class documentation for {@link Stream} and the package documentation
  65  * for <a href="package-summary.html">java.util.stream</a> for additional
  66  * specification of streams, stream operations, stream pipelines, and
  67  * parallelism.
  68  *
  69  * @since 1.8
  70  * @see Stream
  71  * @see <a href="package-summary.html">java.util.stream</a>
  72  */
  73 public interface IntStream extends BaseStream<Integer, IntStream> {
  74 
  75     /**
  76      * Returns a stream consisting of the elements of this stream that match
  77      * the given predicate.
  78      *
  79      * <p>This is an <a href="package-summary.html#StreamOps">intermediate
  80      * operation</a>.
  81      *
  82      * @param predicate a <a href="package-summary.html#NonInterference">non-interfering</a>,
  83      *                  <a href="package-summary.html#Statelessness">stateless</a>
  84      *                  predicate to apply to each element to determine if it
  85      *                  should be included
  86      * @return the new stream
  87      */
  88     IntStream filter(IntPredicate predicate);
  89 
  90     /**
  91      * Returns a stream consisting of the results of applying the given
  92      * function to the elements of this stream.
  93      *
  94      * <p>This is an <a href="package-summary.html#StreamOps">intermediate
  95      * operation</a>.
  96      *
  97      * @param mapper a <a href="package-summary.html#NonInterference">non-interfering</a>,
  98      *               <a href="package-summary.html#Statelessness">stateless</a>
  99      *               function to apply to each element
 100      * @return the new stream
 101      */
 102     IntStream map(IntUnaryOperator mapper);
 103 
 104     /**
 105      * Returns an object-valued {@code Stream} consisting of the results of
 106      * applying the given function to the elements of this stream.
 107      *
 108      * <p>This is an <a href="package-summary.html#StreamOps">
 109      *     intermediate operation</a>.
 110      *
 111      * @param <U> the element type of the new stream
 112      * @param mapper a <a href="package-summary.html#NonInterference">non-interfering</a>,
 113      *               <a href="package-summary.html#Statelessness">stateless</a>
 114      *               function to apply to each element
 115      * @return the new stream
 116      */
 117     <U> Stream<U> mapToObj(IntFunction<? extends U> mapper);
 118 
 119     /**
 120      * Returns a {@code LongStream} consisting of the results of applying the
 121      * given function to the elements of this stream.
 122      *
 123      * <p>This is an <a href="package-summary.html#StreamOps">intermediate
 124      * operation</a>.
 125      *
 126      * @param mapper a <a href="package-summary.html#NonInterference">non-interfering</a>,
 127      *               <a href="package-summary.html#Statelessness">stateless</a>
 128      *               function to apply to each element
 129      * @return the new stream
 130      */
 131     LongStream mapToLong(IntToLongFunction mapper);
 132 
 133     /**
 134      * Returns a {@code DoubleStream} consisting of the results of applying the
 135      * given function to the elements of this stream.
 136      *
 137      * <p>This is an <a href="package-summary.html#StreamOps">intermediate
 138      * operation</a>.
 139      *
 140      * @param mapper a <a href="package-summary.html#NonInterference">non-interfering</a>,
 141      *               <a href="package-summary.html#Statelessness">stateless</a>
 142      *               function to apply to each element
 143      * @return the new stream
 144      */
 145     DoubleStream mapToDouble(IntToDoubleFunction mapper);
 146 
 147     /**
 148      * Returns a stream consisting of the results of replacing each element of
 149      * this stream with the contents of a mapped stream produced by applying
 150      * the provided mapping function to each element.  Each mapped stream is
 151      * {@link java.util.stream.BaseStream#close() closed} after its contents
 152      * have been placed into this stream.  (If a mapped stream is {@code null}
 153      * an empty stream is used, instead.)
 154      *
 155      * <p>This is an <a href="package-summary.html#StreamOps">intermediate
 156      * operation</a>.
 157      *
 158      * @param mapper a <a href="package-summary.html#NonInterference">non-interfering</a>,
 159      *               <a href="package-summary.html#Statelessness">stateless</a>
 160      *               function to apply to each element which produces an
 161      *               {@code IntStream} of new values
 162      * @return the new stream
 163      * @see Stream#flatMap(Function)
 164      */
 165     IntStream flatMap(IntFunction<? extends IntStream> mapper);
 166 
 167     /**
 168      * Returns a stream consisting of the distinct elements of this stream.
 169      *
 170      * <p>This is a <a href="package-summary.html#StreamOps">stateful
 171      * intermediate operation</a>.
 172      *
 173      * @return the new stream
 174      */
 175     IntStream distinct();
 176 
 177     /**
 178      * Returns a stream consisting of the elements of this stream in sorted
 179      * order.
 180      *
 181      * <p>This is a <a href="package-summary.html#StreamOps">stateful
 182      * intermediate operation</a>.
 183      *
 184      * @return the new stream
 185      */
 186     IntStream sorted();
 187 
 188     /**
 189      * Returns a stream consisting of the elements of this stream, additionally
 190      * performing the provided action on each element as elements are consumed
 191      * from the resulting stream.
 192      *
 193      * <p>This is an <a href="package-summary.html#StreamOps">intermediate
 194      * operation</a>.
 195      *
 196      * <p>For parallel stream pipelines, the action may be called at
 197      * whatever time and in whatever thread the element is made available by the
 198      * upstream operation.  If the action modifies shared state,
 199      * it is responsible for providing the required synchronization.
 200      *
 201      * @apiNote This method exists mainly to support debugging, where you want
 202      * to see the elements as they flow past a certain point in a pipeline:
 203      * <pre>{@code
 204      *     IntStream.of(1, 2, 3, 4)
 205      *         .filter(e -> e > 2)
 206      *         .peek(e -> System.out.println("Filtered value: " + e))
 207      *         .map(e -> e * e)
 208      *         .peek(e -> System.out.println("Mapped value: " + e))
 209      *         .sum();
 210      * }</pre>
 211      *
 212      * <p>In cases where the stream implementation is able to optimize away the
 213      * production of some or all the elements (such as with short-circuiting
 214      * operations like {@code findFirst}, or in the example described in
 215      * {@link #count}), the action will not be invoked for those elements.
 216      *
 217      * @param action a <a href="package-summary.html#NonInterference">
 218      *               non-interfering</a> action to perform on the elements as
 219      *               they are consumed from the stream
 220      * @return the new stream
 221      */
 222     IntStream peek(IntConsumer action);
 223 
 224     /**
 225      * Returns a stream consisting of the elements of this stream, truncated
 226      * to be no longer than {@code maxSize} in length.
 227      *
 228      * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
 229      * stateful intermediate operation</a>.
 230      *
 231      * @apiNote
 232      * While {@code limit()} is generally a cheap operation on sequential
 233      * stream pipelines, it can be quite expensive on ordered parallel pipelines,
 234      * especially for large values of {@code maxSize}, since {@code limit(n)}
 235      * is constrained to return not just any <em>n</em> elements, but the
 236      * <em>first n</em> elements in the encounter order.  Using an unordered
 237      * stream source (such as {@link #generate(IntSupplier)}) or removing the
 238      * ordering constraint with {@link #unordered()} may result in significant
 239      * speedups of {@code limit()} in parallel pipelines, if the semantics of
 240      * your situation permit.  If consistency with encounter order is required,
 241      * and you are experiencing poor performance or memory utilization with
 242      * {@code limit()} in parallel pipelines, switching to sequential execution
 243      * with {@link #sequential()} may improve performance.
 244      *
 245      * @param maxSize the number of elements the stream should be limited to
 246      * @return the new stream
 247      * @throws IllegalArgumentException if {@code maxSize} is negative
 248      */
 249     IntStream limit(long maxSize);
 250 
 251     /**
 252      * Returns a stream consisting of the remaining elements of this stream
 253      * after discarding the first {@code n} elements of the stream.
 254      * If this stream contains fewer than {@code n} elements then an
 255      * empty stream will be returned.
 256      *
 257      * <p>This is a <a href="package-summary.html#StreamOps">stateful
 258      * intermediate operation</a>.
 259      *
 260      * @apiNote
 261      * While {@code skip()} is generally a cheap operation on sequential
 262      * stream pipelines, it can be quite expensive on ordered parallel pipelines,
 263      * especially for large values of {@code n}, since {@code skip(n)}
 264      * is constrained to skip not just any <em>n</em> elements, but the
 265      * <em>first n</em> elements in the encounter order.  Using an unordered
 266      * stream source (such as {@link #generate(IntSupplier)}) or removing the
 267      * ordering constraint with {@link #unordered()} may result in significant
 268      * speedups of {@code skip()} in parallel pipelines, if the semantics of
 269      * your situation permit.  If consistency with encounter order is required,
 270      * and you are experiencing poor performance or memory utilization with
 271      * {@code skip()} in parallel pipelines, switching to sequential execution
 272      * with {@link #sequential()} may improve performance.
 273      *
 274      * @param n the number of leading elements to skip
 275      * @return the new stream
 276      * @throws IllegalArgumentException if {@code n} is negative
 277      */
 278     IntStream skip(long n);
 279 
 280     /**
 281      * Returns, if this stream is ordered, a stream consisting of the longest
 282      * prefix of elements taken from this stream that match the given predicate.
 283      * Otherwise returns, if this stream is unordered, a stream consisting of a
 284      * subset of elements taken from this stream that match the given predicate.
 285      *
 286      * <p>If this stream is ordered then the longest prefix is a contiguous
 287      * sequence of elements of this stream that match the given predicate.  The
 288      * first element of the sequence is the first element of this stream, and
 289      * the element immediately following the last element of the sequence does
 290      * not match the given predicate.
 291      *
 292      * <p>If this stream is unordered, and some (but not all) elements of this
 293      * stream match the given predicate, then the behavior of this operation is
 294      * nondeterministic; it is free to take any subset of matching elements
 295      * (which includes the empty set).
 296      *
 297      * <p>Independent of whether this stream is ordered or unordered if all
 298      * elements of this stream match the given predicate then this operation
 299      * takes all elements (the result is the same as the input), or if no
 300      * elements of the stream match the given predicate then no elements are
 301      * taken (the result is an empty stream).
 302      *
 303      * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
 304      * stateful intermediate operation</a>.
 305      *
 306      * @implSpec
 307      * The default implementation obtains the {@link #spliterator() spliterator}
 308      * of this stream, wraps that spliterator so as to support the semantics
 309      * of this operation on traversal, and returns a new stream associated with
 310      * the wrapped spliterator.  The returned stream preserves the execution
 311      * characteristics of this stream (namely parallel or sequential execution
 312      * as per {@link #isParallel()}) but the wrapped spliterator may choose to
 313      * not support splitting.  When the returned stream is closed, the close
 314      * handlers for both the returned and this stream are invoked.
 315      *
 316      * @apiNote
 317      * While {@code takeWhile()} is generally a cheap operation on sequential
 318      * stream pipelines, it can be quite expensive on ordered parallel
 319      * pipelines, since the operation is constrained to return not just any
 320      * valid prefix, but the longest prefix of elements in the encounter order.
 321      * Using an unordered stream source (such as {@link #generate(IntSupplier)})
 322      * or removing the ordering constraint with {@link #unordered()} may result
 323      * in significant speedups of {@code takeWhile()} in parallel pipelines, if
 324      * the semantics of your situation permit.  If consistency with encounter
 325      * order is required, and you are experiencing poor performance or memory
 326      * utilization with {@code takeWhile()} in parallel pipelines, switching to
 327      * sequential execution with {@link #sequential()} may improve performance.
 328      *
 329      * @param predicate a <a href="package-summary.html#NonInterference">non-interfering</a>,
 330      *                  <a href="package-summary.html#Statelessness">stateless</a>
 331      *                  predicate to apply to elements to determine the longest
 332      *                  prefix of elements.
 333      * @return the new stream
 334      * @since 9
 335      */
 336     default IntStream takeWhile(IntPredicate predicate) {
 337         Objects.requireNonNull(predicate);
 338         // Reuses the unordered spliterator, which, when encounter is present,
 339         // is safe to use as long as it configured not to split
 340         return StreamSupport.intStream(
 341                 new WhileOps.UnorderedWhileSpliterator.OfInt.Taking(spliterator(), true, predicate),
 342                 isParallel()).onClose(this::close);
 343     }
 344 
 345     /**
 346      * Returns, if this stream is ordered, a stream consisting of the remaining
 347      * elements of this stream after dropping the longest prefix of elements
 348      * that match the given predicate.  Otherwise returns, if this stream is
 349      * unordered, a stream consisting of the remaining elements of this stream
 350      * after dropping a subset of elements that match the given predicate.
 351      *
 352      * <p>If this stream is ordered then the longest prefix is a contiguous
 353      * sequence of elements of this stream that match the given predicate.  The
 354      * first element of the sequence is the first element of this stream, and
 355      * the element immediately following the last element of the sequence does
 356      * not match the given predicate.
 357      *
 358      * <p>If this stream is unordered, and some (but not all) elements of this
 359      * stream match the given predicate, then the behavior of this operation is
 360      * nondeterministic; it is free to drop any subset of matching elements
 361      * (which includes the empty set).
 362      *
 363      * <p>Independent of whether this stream is ordered or unordered if all
 364      * elements of this stream match the given predicate then this operation
 365      * drops all elements (the result is an empty stream), or if no elements of
 366      * the stream match the given predicate then no elements are dropped (the
 367      * result is the same as the input).
 368      *
 369      * <p>This is a <a href="package-summary.html#StreamOps">stateful
 370      * intermediate operation</a>.
 371      *
 372      * @implSpec
 373      * The default implementation obtains the {@link #spliterator() spliterator}
 374      * of this stream, wraps that spliterator so as to support the semantics
 375      * of this operation on traversal, and returns a new stream associated with
 376      * the wrapped spliterator.  The returned stream preserves the execution
 377      * characteristics of this stream (namely parallel or sequential execution
 378      * as per {@link #isParallel()}) but the wrapped spliterator may choose to
 379      * not support splitting.  When the returned stream is closed, the close
 380      * handlers for both the returned and this stream are invoked.
 381      *
 382      * @apiNote
 383      * While {@code dropWhile()} is generally a cheap operation on sequential
 384      * stream pipelines, it can be quite expensive on ordered parallel
 385      * pipelines, since the operation is constrained to return not just any
 386      * valid prefix, but the longest prefix of elements in the encounter order.
 387      * Using an unordered stream source (such as {@link #generate(IntSupplier)})
 388      * or removing the ordering constraint with {@link #unordered()} may result
 389      * in significant speedups of {@code dropWhile()} in parallel pipelines, if
 390      * the semantics of your situation permit.  If consistency with encounter
 391      * order is required, and you are experiencing poor performance or memory
 392      * utilization with {@code dropWhile()} in parallel pipelines, switching to
 393      * sequential execution with {@link #sequential()} may improve performance.
 394      *
 395      * @param predicate a <a href="package-summary.html#NonInterference">non-interfering</a>,
 396      *                  <a href="package-summary.html#Statelessness">stateless</a>
 397      *                  predicate to apply to elements to determine the longest
 398      *                  prefix of elements.
 399      * @return the new stream
 400      * @since 9
 401      */
 402     default IntStream dropWhile(IntPredicate predicate) {
 403         Objects.requireNonNull(predicate);
 404         // Reuses the unordered spliterator, which, when encounter is present,
 405         // is safe to use as long as it configured not to split
 406         return StreamSupport.intStream(
 407                 new WhileOps.UnorderedWhileSpliterator.OfInt.Dropping(spliterator(), true, predicate),
 408                 isParallel()).onClose(this::close);
 409     }
 410 
 411     /**
 412      * Performs an action for each element of this stream.
 413      *
 414      * <p>This is a <a href="package-summary.html#StreamOps">terminal
 415      * operation</a>.
 416      *
 417      * <p>For parallel stream pipelines, this operation does <em>not</em>
 418      * guarantee to respect the encounter order of the stream, as doing so
 419      * would sacrifice the benefit of parallelism.  For any given element, the
 420      * action may be performed at whatever time and in whatever thread the
 421      * library chooses.  If the action accesses shared state, it is
 422      * responsible for providing the required synchronization.
 423      *
 424      * @param action a <a href="package-summary.html#NonInterference">
 425      *               non-interfering</a> action to perform on the elements
 426      */
 427     void forEach(IntConsumer action);
 428 
 429     /**
 430      * Performs an action for each element of this stream, guaranteeing that
 431      * each element is processed in encounter order for streams that have a
 432      * defined encounter order.
 433      *
 434      * <p>This is a <a href="package-summary.html#StreamOps">terminal
 435      * operation</a>.
 436      *
 437      * @param action a <a href="package-summary.html#NonInterference">
 438      *               non-interfering</a> action to perform on the elements
 439      * @see #forEach(IntConsumer)
 440      */
 441     void forEachOrdered(IntConsumer action);
 442 
 443     /**
 444      * Returns an array containing the elements of this stream.
 445      *
 446      * <p>This is a <a href="package-summary.html#StreamOps">terminal
 447      * operation</a>.
 448      *
 449      * @return an array containing the elements of this stream
 450      */
 451     int[] toArray();
 452 
 453     /**
 454      * Performs a <a href="package-summary.html#Reduction">reduction</a> on the
 455      * elements of this stream, using the provided identity value and an
 456      * <a href="package-summary.html#Associativity">associative</a>
 457      * accumulation function, and returns the reduced value.  This is equivalent
 458      * to:
 459      * <pre>{@code
 460      *     int result = identity;
 461      *     for (int element : this stream)
 462      *         result = accumulator.applyAsInt(result, element)
 463      *     return result;
 464      * }</pre>
 465      *
 466      * but is not constrained to execute sequentially.
 467      *
 468      * <p>The {@code identity} value must be an identity for the accumulator
 469      * function. This means that for all {@code x},
 470      * {@code accumulator.apply(identity, x)} is equal to {@code x}.
 471      * The {@code accumulator} function must be an
 472      * <a href="package-summary.html#Associativity">associative</a> function.
 473      *
 474      * <p>This is a <a href="package-summary.html#StreamOps">terminal
 475      * operation</a>.
 476      *
 477      * @apiNote Sum, min, max, and average are all special cases of reduction.
 478      * Summing a stream of numbers can be expressed as:
 479      *
 480      * <pre>{@code
 481      *     int sum = integers.reduce(0, (a, b) -> a+b);
 482      * }</pre>
 483      *
 484      * or more compactly:
 485      *
 486      * <pre>{@code
 487      *     int sum = integers.reduce(0, Integer::sum);
 488      * }</pre>
 489      *
 490      * <p>While this may seem a more roundabout way to perform an aggregation
 491      * compared to simply mutating a running total in a loop, reduction
 492      * operations parallelize more gracefully, without needing additional
 493      * synchronization and with greatly reduced risk of data races.
 494      *
 495      * @param identity the identity value for the accumulating function
 496      * @param op an <a href="package-summary.html#Associativity">associative</a>,
 497      *           <a href="package-summary.html#NonInterference">non-interfering</a>,
 498      *           <a href="package-summary.html#Statelessness">stateless</a>
 499      *           function for combining two values
 500      * @return the result of the reduction
 501      * @see #sum()
 502      * @see #min()
 503      * @see #max()
 504      * @see #average()
 505      */
 506     int reduce(int identity, IntBinaryOperator op);
 507 
 508     /**
 509      * Performs a <a href="package-summary.html#Reduction">reduction</a> on the
 510      * elements of this stream, using an
 511      * <a href="package-summary.html#Associativity">associative</a> accumulation
 512      * function, and returns an {@code OptionalInt} describing the reduced value,
 513      * if any. This is equivalent to:
 514      * <pre>{@code
 515      *     boolean foundAny = false;
 516      *     int result = null;
 517      *     for (int element : this stream) {
 518      *         if (!foundAny) {
 519      *             foundAny = true;
 520      *             result = element;
 521      *         }
 522      *         else
 523      *             result = accumulator.applyAsInt(result, element);
 524      *     }
 525      *     return foundAny ? OptionalInt.of(result) : OptionalInt.empty();
 526      * }</pre>
 527      *
 528      * but is not constrained to execute sequentially.
 529      *
 530      * <p>The {@code accumulator} function must be an
 531      * <a href="package-summary.html#Associativity">associative</a> function.
 532      *
 533      * <p>This is a <a href="package-summary.html#StreamOps">terminal
 534      * operation</a>.
 535      *
 536      * @param op an <a href="package-summary.html#Associativity">associative</a>,
 537      *           <a href="package-summary.html#NonInterference">non-interfering</a>,
 538      *           <a href="package-summary.html#Statelessness">stateless</a>
 539      *           function for combining two values
 540      * @return the result of the reduction
 541      * @see #reduce(int, IntBinaryOperator)
 542      */
 543     OptionalInt reduce(IntBinaryOperator op);
 544 
 545     /**
 546      * Performs a <a href="package-summary.html#MutableReduction">mutable
 547      * reduction</a> operation on the elements of this stream.  A mutable
 548      * reduction is one in which the reduced value is a mutable result container,
 549      * such as an {@code ArrayList}, and elements are incorporated by updating
 550      * the state of the result rather than by replacing the result.  This
 551      * produces a result equivalent to:
 552      * <pre>{@code
 553      *     R result = supplier.get();
 554      *     for (int element : this stream)
 555      *         accumulator.accept(result, element);
 556      *     return result;
 557      * }</pre>
 558      *
 559      * <p>Like {@link #reduce(int, IntBinaryOperator)}, {@code collect} operations
 560      * can be parallelized without requiring additional synchronization.
 561      *
 562      * <p>This is a <a href="package-summary.html#StreamOps">terminal
 563      * operation</a>.
 564      *
 565      * @param <R> the type of the mutable result container
 566      * @param supplier a function that creates a new mutable result container.
 567      *                 For a parallel execution, this function may be called
 568      *                 multiple times and must return a fresh value each time.
 569      * @param accumulator an <a href="package-summary.html#Associativity">associative</a>,
 570      *                    <a href="package-summary.html#NonInterference">non-interfering</a>,
 571      *                    <a href="package-summary.html#Statelessness">stateless</a>
 572      *                    function that must fold an element into a result
 573      *                    container.
 574      * @param combiner an <a href="package-summary.html#Associativity">associative</a>,
 575      *                    <a href="package-summary.html#NonInterference">non-interfering</a>,
 576      *                    <a href="package-summary.html#Statelessness">stateless</a>
 577      *                    function that accepts two partial result containers
 578      *                    and merges them, which must be compatible with the
 579      *                    accumulator function.  The combiner function must fold
 580      *                    the elements from the second result container into the
 581      *                    first result container.
 582      * @return the result of the reduction
 583      * @see Stream#collect(Supplier, BiConsumer, BiConsumer)
 584      */
 585     <R> R collect(Supplier<R> supplier,
 586                   ObjIntConsumer<R> accumulator,
 587                   BiConsumer<R, R> combiner);
 588 
 589     /**
 590      * Returns the sum of elements in this stream.  This is a special case
 591      * of a <a href="package-summary.html#Reduction">reduction</a>
 592      * and is equivalent to:
 593      * <pre>{@code
 594      *     return reduce(0, Integer::sum);
 595      * }</pre>
 596      *
 597      * <p>This is a <a href="package-summary.html#StreamOps">terminal
 598      * operation</a>.
 599      *
 600      * @return the sum of elements in this stream
 601      */
 602     int sum();
 603 
 604     /**
 605      * Returns an {@code OptionalInt} describing the minimum element of this
 606      * stream, or an empty optional if this stream is empty.  This is a special
 607      * case of a <a href="package-summary.html#Reduction">reduction</a>
 608      * and is equivalent to:
 609      * <pre>{@code
 610      *     return reduce(Integer::min);
 611      * }</pre>
 612      *
 613      * <p>This is a <a href="package-summary.html#StreamOps">terminal operation</a>.
 614      *
 615      * @return an {@code OptionalInt} containing the minimum element of this
 616      * stream, or an empty {@code OptionalInt} if the stream is empty
 617      */
 618     OptionalInt min();
 619 
 620     /**
 621      * Returns an {@code OptionalInt} describing the maximum element of this
 622      * stream, or an empty optional if this stream is empty.  This is a special
 623      * case of a <a href="package-summary.html#Reduction">reduction</a>
 624      * and is equivalent to:
 625      * <pre>{@code
 626      *     return reduce(Integer::max);
 627      * }</pre>
 628      *
 629      * <p>This is a <a href="package-summary.html#StreamOps">terminal
 630      * operation</a>.
 631      *
 632      * @return an {@code OptionalInt} containing the maximum element of this
 633      * stream, or an empty {@code OptionalInt} if the stream is empty
 634      */
 635     OptionalInt max();
 636 
 637     /**
 638      * Returns the count of elements in this stream.  This is a special case of
 639      * a <a href="package-summary.html#Reduction">reduction</a> and is
 640      * equivalent to:
 641      * <pre>{@code
 642      *     return mapToLong(e -> 1L).sum();
 643      * }</pre>
 644      *
 645      * <p>This is a <a href="package-summary.html#StreamOps">terminal operation</a>.
 646      *
 647      * @apiNote
 648      * An implementation may choose to not execute the stream pipeline (either
 649      * sequentially or in parallel) if it is capable of computing the count
 650      * directly from the stream source.  In such cases no source elements will
 651      * be traversed and no intermediate operations will be evaluated.
 652      * Behavioral parameters with side-effects, which are strongly discouraged
 653      * except for harmless cases such as debugging, may be affected.  For
 654      * example, consider the following stream:
 655      * <pre>{@code
 656      *     IntStream s = IntStream.of(1, 2, 3, 4);
 657      *     long count = s.peek(System.out::println).count();
 658      * }</pre>
 659      * The number of elements covered by the stream source is known and the
 660      * intermediate operation, {@code peek}, does not inject into or remove
 661      * elements from the stream (as may be the case for {@code flatMap} or
 662      * {@code filter} operations).  Thus the count is 4 and there is no need to
 663      * execute the pipeline and, as a side-effect, print out the elements.
 664      *
 665      * @return the count of elements in this stream
 666      */
 667     long count();
 668 
 669     /**
 670      * Returns an {@code OptionalDouble} describing the arithmetic mean of elements of
 671      * this stream, or an empty optional if this stream is empty.  This is a
 672      * special case of a
 673      * <a href="package-summary.html#Reduction">reduction</a>.
 674      *
 675      * <p>This is a <a href="package-summary.html#StreamOps">terminal
 676      * operation</a>.
 677      *
 678      * @return an {@code OptionalDouble} containing the average element of this
 679      * stream, or an empty optional if the stream is empty
 680      */
 681     OptionalDouble average();
 682 
 683     /**
 684      * Returns an {@code IntSummaryStatistics} describing various
 685      * summary data about the elements of this stream.  This is a special
 686      * case of a <a href="package-summary.html#Reduction">reduction</a>.
 687      *
 688      * <p>This is a <a href="package-summary.html#StreamOps">terminal
 689      * operation</a>.
 690      *
 691      * @return an {@code IntSummaryStatistics} describing various summary data
 692      * about the elements of this stream
 693      */
 694     IntSummaryStatistics summaryStatistics();
 695 
 696     /**
 697      * Returns whether any elements of this stream match the provided
 698      * predicate.  May not evaluate the predicate on all elements if not
 699      * necessary for determining the result.  If the stream is empty then
 700      * {@code false} is returned and the predicate is not evaluated.
 701      *
 702      * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
 703      * terminal operation</a>.
 704      *
 705      * @apiNote
 706      * This method evaluates the <em>existential quantification</em> of the
 707      * predicate over the elements of the stream (for some x P(x)).
 708      *
 709      * @param predicate a <a href="package-summary.html#NonInterference">non-interfering</a>,
 710      *                  <a href="package-summary.html#Statelessness">stateless</a>
 711      *                  predicate to apply to elements of this stream
 712      * @return {@code true} if any elements of the stream match the provided
 713      * predicate, otherwise {@code false}
 714      */
 715     boolean anyMatch(IntPredicate predicate);
 716 
 717     /**
 718      * Returns whether all elements of this stream match the provided predicate.
 719      * May not evaluate the predicate on all elements if not necessary for
 720      * determining the result.  If the stream is empty then {@code true} is
 721      * returned and the predicate is not evaluated.
 722      *
 723      * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
 724      * terminal operation</a>.
 725      *
 726      * @apiNote
 727      * This method evaluates the <em>universal quantification</em> of the
 728      * predicate over the elements of the stream (for all x P(x)).  If the
 729      * stream is empty, the quantification is said to be <em>vacuously
 730      * satisfied</em> and is always {@code true} (regardless of P(x)).
 731      *
 732      * @param predicate a <a href="package-summary.html#NonInterference">non-interfering</a>,
 733      *                  <a href="package-summary.html#Statelessness">stateless</a>
 734      *                  predicate to apply to elements of this stream
 735      * @return {@code true} if either all elements of the stream match the
 736      * provided predicate or the stream is empty, otherwise {@code false}
 737      */
 738     boolean allMatch(IntPredicate predicate);
 739 
 740     /**
 741      * Returns whether no elements of this stream match the provided predicate.
 742      * May not evaluate the predicate on all elements if not necessary for
 743      * determining the result.  If the stream is empty then {@code true} is
 744      * returned and the predicate is not evaluated.
 745      *
 746      * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
 747      * terminal operation</a>.
 748      *
 749      * @apiNote
 750      * This method evaluates the <em>universal quantification</em> of the
 751      * negated predicate over the elements of the stream (for all x ~P(x)).  If
 752      * the stream is empty, the quantification is said to be vacuously satisfied
 753      * and is always {@code true}, regardless of P(x).
 754      *
 755      * @param predicate a <a href="package-summary.html#NonInterference">non-interfering</a>,
 756      *                  <a href="package-summary.html#Statelessness">stateless</a>
 757      *                  predicate to apply to elements of this stream
 758      * @return {@code true} if either no elements of the stream match the
 759      * provided predicate or the stream is empty, otherwise {@code false}
 760      */
 761     boolean noneMatch(IntPredicate predicate);
 762 
 763     /**
 764      * Returns an {@link OptionalInt} describing the first element of this
 765      * stream, or an empty {@code OptionalInt} if the stream is empty.  If the
 766      * stream has no encounter order, then any element may be returned.
 767      *
 768      * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
 769      * terminal operation</a>.
 770      *
 771      * @return an {@code OptionalInt} describing the first element of this stream,
 772      * or an empty {@code OptionalInt} if the stream is empty
 773      */
 774     OptionalInt findFirst();
 775 
 776     /**
 777      * Returns an {@link OptionalInt} describing some element of the stream, or
 778      * an empty {@code OptionalInt} if the stream is empty.
 779      *
 780      * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
 781      * terminal operation</a>.
 782      *
 783      * <p>The behavior of this operation is explicitly nondeterministic; it is
 784      * free to select any element in the stream.  This is to allow for maximal
 785      * performance in parallel operations; the cost is that multiple invocations
 786      * on the same source may not return the same result.  (If a stable result
 787      * is desired, use {@link #findFirst()} instead.)
 788      *
 789      * @return an {@code OptionalInt} describing some element of this stream, or
 790      * an empty {@code OptionalInt} if the stream is empty
 791      * @see #findFirst()
 792      */
 793     OptionalInt findAny();
 794 
 795     /**
 796      * Returns a {@code LongStream} consisting of the elements of this stream,
 797      * converted to {@code long}.
 798      *
 799      * <p>This is an <a href="package-summary.html#StreamOps">intermediate
 800      * operation</a>.
 801      *
 802      * @return a {@code LongStream} consisting of the elements of this stream,
 803      * converted to {@code long}
 804      */
 805     LongStream asLongStream();
 806 
 807     /**
 808      * Returns a {@code DoubleStream} consisting of the elements of this stream,
 809      * converted to {@code double}.
 810      *
 811      * <p>This is an <a href="package-summary.html#StreamOps">intermediate
 812      * operation</a>.
 813      *
 814      * @return a {@code DoubleStream} consisting of the elements of this stream,
 815      * converted to {@code double}
 816      */
 817     DoubleStream asDoubleStream();
 818 
 819     /**
 820      * Returns a {@code Stream} consisting of the elements of this stream,
 821      * each boxed to an {@code Integer}.
 822      *
 823      * <p>This is an <a href="package-summary.html#StreamOps">intermediate
 824      * operation</a>.
 825      *
 826      * @return a {@code Stream} consistent of the elements of this stream,
 827      * each boxed to an {@code Integer}
 828      */
 829     Stream<Integer> boxed();
 830 
 831     @Override
 832     IntStream sequential();
 833 
 834     @Override
 835     IntStream parallel();
 836 
 837     @Override
 838     PrimitiveIterator.OfInt iterator();
 839 
 840     @Override
 841     Spliterator.OfInt spliterator();
 842 
 843     // Static factories
 844 
 845     /**
 846      * Returns a builder for an {@code IntStream}.
 847      *
 848      * @return a stream builder
 849      */
 850     public static Builder builder() {
 851         return new Streams.IntStreamBuilderImpl();
 852     }
 853 
 854     /**
 855      * Returns an empty sequential {@code IntStream}.
 856      *
 857      * @return an empty sequential stream
 858      */
 859     public static IntStream empty() {
 860         return StreamSupport.intStream(Spliterators.emptyIntSpliterator(), false);
 861     }
 862 
 863     /**
 864      * Returns a sequential {@code IntStream} containing a single element.
 865      *
 866      * @param t the single element
 867      * @return a singleton sequential stream
 868      */
 869     public static IntStream of(int t) {
 870         return StreamSupport.intStream(new Streams.IntStreamBuilderImpl(t), false);
 871     }
 872 
 873     /**
 874      * Returns a sequential ordered stream whose elements are the specified values.
 875      *
 876      * @param values the elements of the new stream
 877      * @return the new stream
 878      */
 879     public static IntStream of(int... values) {
 880         return Arrays.stream(values);
 881     }
 882 
 883     /**
 884      * Returns an infinite sequential ordered {@code IntStream} produced by iterative
 885      * application of a function {@code f} to an initial element {@code seed},
 886      * producing a {@code Stream} consisting of {@code seed}, {@code f(seed)},
 887      * {@code f(f(seed))}, etc.
 888      *
 889      * <p>The first element (position {@code 0}) in the {@code IntStream} will be
 890      * the provided {@code seed}.  For {@code n > 0}, the element at position
 891      * {@code n}, will be the result of applying the function {@code f} to the
 892      * element at position {@code n - 1}.
 893      *
 894      * <p>The action of applying {@code f} for one element
 895      * <a href="../concurrent/package-summary.html#MemoryVisibility"><i>happens-before</i></a>
 896      * the action of applying {@code f} for subsequent elements.  For any given
 897      * element the action may be performed in whatever thread the library
 898      * chooses.
 899      *
 900      * @param seed the initial element
 901      * @param f a function to be applied to the previous element to produce
 902      *          a new element
 903      * @return a new sequential {@code IntStream}
 904      */
 905     public static IntStream iterate(final int seed, final IntUnaryOperator f) {
 906         Objects.requireNonNull(f);
 907         Spliterator.OfInt spliterator = new Spliterators.AbstractIntSpliterator(Long.MAX_VALUE,
 908                Spliterator.ORDERED | Spliterator.IMMUTABLE | Spliterator.NONNULL) {
 909             int prev;
 910             boolean started;
 911 
 912             @Override
 913             public boolean tryAdvance(IntConsumer action) {
 914                 Objects.requireNonNull(action);
 915                 int t;
 916                 if (started)
 917                     t = f.applyAsInt(prev);
 918                 else {
 919                     t = seed;
 920                     started = true;
 921                 }
 922                 action.accept(prev = t);
 923                 return true;
 924             }
 925         };
 926         return StreamSupport.intStream(spliterator, false);
 927     }
 928 
 929     /**
 930      * Returns a sequential ordered {@code IntStream} produced by iterative
 931      * application of the given {@code next} function to an initial element,
 932      * conditioned on satisfying the given {@code hasNext} predicate.  The
 933      * stream terminates as soon as the {@code hasNext} predicate returns false.
 934      *
 935      * <p>{@code IntStream.iterate} should produce the same sequence of elements as
 936      * produced by the corresponding for-loop:
 937      * <pre>{@code
 938      *     for (int index=seed; hasNext.test(index); index = next.applyAsInt(index)) {
 939      *         ...
 940      *     }
 941      * }</pre>
 942      *
 943      * <p>The resulting sequence may be empty if the {@code hasNext} predicate
 944      * does not hold on the seed value.  Otherwise the first element will be the
 945      * supplied {@code seed} value, the next element (if present) will be the
 946      * result of applying the {@code next} function to the {@code seed} value,
 947      * and so on iteratively until the {@code hasNext} predicate indicates that
 948      * the stream should terminate.
 949      *
 950      * <p>The action of applying the {@code hasNext} predicate to an element
 951      * <a href="../concurrent/package-summary.html#MemoryVisibility"><i>happens-before</i></a>
 952      * the action of applying the {@code next} function to that element.  The
 953      * action of applying the {@code next} function for one element
 954      * <i>happens-before</i> the action of applying the {@code hasNext}
 955      * predicate for subsequent elements.  For any given element an action may
 956      * be performed in whatever thread the library chooses.
 957      *
 958      * @param seed the initial element
 959      * @param hasNext a predicate to apply to elements to determine when the
 960      *                stream must terminate.
 961      * @param next a function to be applied to the previous element to produce
 962      *             a new element
 963      * @return a new sequential {@code IntStream}
 964      * @since 9
 965      */
 966     public static IntStream iterate(int seed, IntPredicate hasNext, IntUnaryOperator next) {
 967         Objects.requireNonNull(next);
 968         Objects.requireNonNull(hasNext);
 969         Spliterator.OfInt spliterator = new Spliterators.AbstractIntSpliterator(Long.MAX_VALUE,
 970                Spliterator.ORDERED | Spliterator.IMMUTABLE | Spliterator.NONNULL) {
 971             int prev;
 972             boolean started, finished;
 973 
 974             @Override
 975             public boolean tryAdvance(IntConsumer action) {
 976                 Objects.requireNonNull(action);
 977                 if (finished)
 978                     return false;
 979                 int t;
 980                 if (started)
 981                     t = next.applyAsInt(prev);
 982                 else {
 983                     t = seed;
 984                     started = true;
 985                 }
 986                 if (!hasNext.test(t)) {
 987                     finished = true;
 988                     return false;
 989                 }
 990                 action.accept(prev = t);
 991                 return true;
 992             }
 993 
 994             @Override
 995             public void forEachRemaining(IntConsumer action) {
 996                 Objects.requireNonNull(action);
 997                 if (finished)
 998                     return;
 999                 finished = true;
1000                 int t = started ? next.applyAsInt(prev) : seed;
1001                 while (hasNext.test(t)) {
1002                     action.accept(t);
1003                     t = next.applyAsInt(t);
1004                 }
1005             }
1006         };
1007         return StreamSupport.intStream(spliterator, false);
1008     }
1009 
1010     /**
1011      * Returns an infinite sequential unordered stream where each element is
1012      * generated by the provided {@code IntSupplier}.  This is suitable for
1013      * generating constant streams, streams of random elements, etc.
1014      *
1015      * @param s the {@code IntSupplier} for generated elements
1016      * @return a new infinite sequential unordered {@code IntStream}
1017      */
1018     public static IntStream generate(IntSupplier s) {
1019         Objects.requireNonNull(s);
1020         return StreamSupport.intStream(
1021                 new StreamSpliterators.InfiniteSupplyingSpliterator.OfInt(Long.MAX_VALUE, s), false);
1022     }
1023 
1024     /**
1025      * Returns a sequential ordered {@code IntStream} from {@code startInclusive}
1026      * (inclusive) to {@code endExclusive} (exclusive) by an incremental step of
1027      * {@code 1}.
1028      *
1029      * @apiNote
1030      * <p>An equivalent sequence of increasing values can be produced
1031      * sequentially using a {@code for} loop as follows:
1032      * <pre>{@code
1033      *     for (int i = startInclusive; i < endExclusive ; i++) { ... }
1034      * }</pre>
1035      *
1036      * @param startInclusive the (inclusive) initial value
1037      * @param endExclusive the exclusive upper bound
1038      * @return a sequential {@code IntStream} for the range of {@code int}
1039      *         elements
1040      */
1041     public static IntStream range(int startInclusive, int endExclusive) {
1042         if (startInclusive >= endExclusive) {
1043             return empty();
1044         } else {
1045             return StreamSupport.intStream(
1046                     new Streams.RangeIntSpliterator(startInclusive, endExclusive, false), false);
1047         }
1048     }
1049 
1050     /**
1051      * Returns a sequential ordered {@code IntStream} from {@code startInclusive}
1052      * (inclusive) to {@code endInclusive} (inclusive) by an incremental step of
1053      * {@code 1}.
1054      *
1055      * @apiNote
1056      * <p>An equivalent sequence of increasing values can be produced
1057      * sequentially using a {@code for} loop as follows:
1058      * <pre>{@code
1059      *     for (int i = startInclusive; i <= endInclusive ; i++) { ... }
1060      * }</pre>
1061      *
1062      * @param startInclusive the (inclusive) initial value
1063      * @param endInclusive the inclusive upper bound
1064      * @return a sequential {@code IntStream} for the range of {@code int}
1065      *         elements
1066      */
1067     public static IntStream rangeClosed(int startInclusive, int endInclusive) {
1068         if (startInclusive > endInclusive) {
1069             return empty();
1070         } else {
1071             return StreamSupport.intStream(
1072                     new Streams.RangeIntSpliterator(startInclusive, endInclusive, true), false);
1073         }
1074     }
1075 
1076     /**
1077      * Creates a lazily concatenated stream whose elements are all the
1078      * elements of the first stream followed by all the elements of the
1079      * second stream.  The resulting stream is ordered if both
1080      * of the input streams are ordered, and parallel if either of the input
1081      * streams is parallel.  When the resulting stream is closed, the close
1082      * handlers for both input streams are invoked.
1083      *
1084      * <p>This method operates on the two input streams and binds each stream
1085      * to its source.  As a result subsequent modifications to an input stream
1086      * source may not be reflected in the concatenated stream result.
1087      *
1088      * @implNote
1089      * Use caution when constructing streams from repeated concatenation.
1090      * Accessing an element of a deeply concatenated stream can result in deep
1091      * call chains, or even {@code StackOverflowError}.
1092      *
1093      * @apiNote
1094      * To preserve optimization opportunities this method binds each stream to
1095      * its source and accepts only two streams as parameters.  For example, the
1096      * exact size of the concatenated stream source can be computed if the exact
1097      * size of each input stream source is known.
1098      * To concatenate more streams without binding, or without nested calls to
1099      * this method, try creating a stream of streams and flat-mapping with the
1100      * identity function, for example:
1101      * <pre>{@code
1102      *     IntStream concat = Stream.of(s1, s2, s3, s4).flatMapToInt(s -> s);
1103      * }</pre>
1104      *
1105      * @param a the first stream
1106      * @param b the second stream
1107      * @return the concatenation of the two input streams
1108      */
1109     public static IntStream concat(IntStream a, IntStream b) {
1110         Objects.requireNonNull(a);
1111         Objects.requireNonNull(b);
1112 
1113         Spliterator.OfInt split = new Streams.ConcatSpliterator.OfInt(
1114                 a.spliterator(), b.spliterator());
1115         IntStream stream = StreamSupport.intStream(split, a.isParallel() || b.isParallel());
1116         return stream.onClose(Streams.composedClose(a, b));
1117     }
1118 
1119     /**
1120      * A mutable builder for an {@code IntStream}.
1121      *
1122      * <p>A stream builder has a lifecycle, which starts in a building
1123      * phase, during which elements can be added, and then transitions to a built
1124      * phase, after which elements may not be added.  The built phase
1125      * begins when the {@link #build()} method is called, which creates an
1126      * ordered stream whose elements are the elements that were added to the
1127      * stream builder, in the order they were added.
1128      *
1129      * @see IntStream#builder()
1130      * @since 1.8
1131      */
1132     public interface Builder extends IntConsumer {
1133 
1134         /**
1135          * Adds an element to the stream being built.
1136          *
1137          * @throws IllegalStateException if the builder has already transitioned
1138          * to the built state
1139          */
1140         @Override
1141         void accept(int t);
1142 
1143         /**
1144          * Adds an element to the stream being built.
1145          *
1146          * @implSpec
1147          * The default implementation behaves as if:
1148          * <pre>{@code
1149          *     accept(t)
1150          *     return this;
1151          * }</pre>
1152          *
1153          * @param t the element to add
1154          * @return {@code this} builder
1155          * @throws IllegalStateException if the builder has already transitioned
1156          * to the built state
1157          */
1158         default Builder add(int t) {
1159             accept(t);
1160             return this;
1161         }
1162 
1163         /**
1164          * Builds the stream, transitioning this builder to the built state.
1165          * An {@code IllegalStateException} is thrown if there are further
1166          * attempts to operate on the builder after it has entered the built
1167          * state.
1168          *
1169          * @return the built stream
1170          * @throws IllegalStateException if the builder has already transitioned to
1171          * the built state
1172          */
1173         IntStream build();
1174     }
1175 }