jdk/src/java.base/share/classes/java/util/stream/LongStream.java
author psandoz
Fri, 31 Jul 2015 12:29:01 +0200
changeset 32002 e378c0dc767e
parent 31644 dbca10d053fd
child 35302 e4d2275861c3
permissions -rw-r--r--
8130828: Fix some typos and omissions in the the j.u.stream JavaDoc Reviewed-by: smarks
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
17167
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
     1
/*
31644
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
     2
 * Copyright (c) 2013, 2015, Oracle and/or its affiliates. All rights reserved.
17167
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
     3
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
     4
 *
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
     5
 * This code is free software; you can redistribute it and/or modify it
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
     6
 * under the terms of the GNU General Public License version 2 only, as
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
     7
 * published by the Free Software Foundation.  Oracle designates this
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
     8
 * particular file as subject to the "Classpath" exception as provided
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
     9
 * by Oracle in the LICENSE file that accompanied this code.
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
    10
 *
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
    11
 * This code is distributed in the hope that it will be useful, but WITHOUT
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
    12
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
    13
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
    14
 * version 2 for more details (a copy is included in the LICENSE file that
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
    15
 * accompanied this code).
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
    16
 *
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
    17
 * You should have received a copy of the GNU General Public License version
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
    18
 * 2 along with this work; if not, write to the Free Software Foundation,
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
    19
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
    20
 *
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
    21
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
    22
 * or visit www.oracle.com if you need additional information or have any
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
    23
 * questions.
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
    24
 */
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
    25
package java.util.stream;
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
    26
17195
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
    27
import java.util.Arrays;
17167
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
    28
import java.util.LongSummaryStatistics;
17195
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
    29
import java.util.Objects;
17167
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
    30
import java.util.OptionalDouble;
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
    31
import java.util.OptionalLong;
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
    32
import java.util.PrimitiveIterator;
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
    33
import java.util.Spliterator;
17195
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
    34
import java.util.Spliterators;
17167
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
    35
import java.util.function.BiConsumer;
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
    36
import java.util.function.Function;
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
    37
import java.util.function.LongBinaryOperator;
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
    38
import java.util.function.LongConsumer;
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
    39
import java.util.function.LongFunction;
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
    40
import java.util.function.LongPredicate;
17195
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
    41
import java.util.function.LongSupplier;
17167
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
    42
import java.util.function.LongToDoubleFunction;
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
    43
import java.util.function.LongToIntFunction;
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
    44
import java.util.function.LongUnaryOperator;
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
    45
import java.util.function.ObjLongConsumer;
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
    46
import java.util.function.Supplier;
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
    47
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
    48
/**
21339
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
    49
 * A sequence of primitive long-valued elements supporting sequential and parallel
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
    50
 * aggregate operations.  This is the {@code long} primitive specialization of
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
    51
 * {@link Stream}.
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
    52
 *
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
    53
 * <p>The following example illustrates an aggregate operation using
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
    54
 * {@link Stream} and {@link LongStream}, computing the sum of the weights of the
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
    55
 * red widgets:
19850
93b368e54c1c 8011916: Spec update for java.util.stream
henryjen
parents: 19800
diff changeset
    56
 *
93b368e54c1c 8011916: Spec update for java.util.stream
henryjen
parents: 19800
diff changeset
    57
 * <pre>{@code
93b368e54c1c 8011916: Spec update for java.util.stream
henryjen
parents: 19800
diff changeset
    58
 *     long sum = widgets.stream()
93b368e54c1c 8011916: Spec update for java.util.stream
henryjen
parents: 19800
diff changeset
    59
 *                       .filter(w -> w.getColor() == RED)
93b368e54c1c 8011916: Spec update for java.util.stream
henryjen
parents: 19800
diff changeset
    60
 *                       .mapToLong(w -> w.getWeight())
93b368e54c1c 8011916: Spec update for java.util.stream
henryjen
parents: 19800
diff changeset
    61
 *                       .sum();
93b368e54c1c 8011916: Spec update for java.util.stream
henryjen
parents: 19800
diff changeset
    62
 * }</pre>
93b368e54c1c 8011916: Spec update for java.util.stream
henryjen
parents: 19800
diff changeset
    63
 *
21339
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
    64
 * See the class documentation for {@link Stream} and the package documentation
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
    65
 * for <a href="package-summary.html">java.util.stream</a> for additional
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
    66
 * specification of streams, stream operations, stream pipelines, and
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
    67
 * parallelism.
17167
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
    68
 *
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
    69
 * @since 1.8
21339
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
    70
 * @see Stream
17167
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
    71
 * @see <a href="package-summary.html">java.util.stream</a>
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
    72
 */
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
    73
public interface LongStream extends BaseStream<Long, LongStream> {
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
    74
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
    75
    /**
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
    76
     * Returns a stream consisting of the elements of this stream that match
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
    77
     * the given predicate.
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
    78
     *
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
    79
     * <p>This is an <a href="package-summary.html#StreamOps">intermediate
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
    80
     * operation</a>.
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
    81
     *
21339
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
    82
     * @param predicate a <a href="package-summary.html#NonInterference">non-interfering</a>,
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
    83
     *                  <a href="package-summary.html#Statelessness">stateless</a>
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
    84
     *                  predicate to apply to each element to determine if it
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
    85
     *                  should be included
17167
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
    86
     * @return the new stream
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
    87
     */
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
    88
    LongStream filter(LongPredicate predicate);
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
    89
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
    90
    /**
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
    91
     * Returns a stream consisting of the results of applying the given
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
    92
     * function to the elements of this stream.
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
    93
     *
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
    94
     * <p>This is an <a href="package-summary.html#StreamOps">intermediate
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
    95
     * operation</a>.
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
    96
     *
21339
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
    97
     * @param mapper a <a href="package-summary.html#NonInterference">non-interfering</a>,
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
    98
     *               <a href="package-summary.html#Statelessness">stateless</a>
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
    99
     *               function to apply to each element
17167
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   100
     * @return the new stream
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   101
     */
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   102
    LongStream map(LongUnaryOperator mapper);
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   103
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   104
    /**
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   105
     * Returns an object-valued {@code Stream} consisting of the results of
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   106
     * applying the given function to the elements of this stream.
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   107
     *
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   108
     * <p>This is an <a href="package-summary.html#StreamOps">
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   109
     *     intermediate operation</a>.
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   110
     *
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   111
     * @param <U> the element type of the new stream
21339
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   112
     * @param mapper a <a href="package-summary.html#NonInterference">non-interfering</a>,
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   113
     *               <a href="package-summary.html#Statelessness">stateless</a>
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   114
     *               function to apply to each element
17167
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   115
     * @return the new stream
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   116
     */
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   117
    <U> Stream<U> mapToObj(LongFunction<? extends U> mapper);
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   118
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   119
    /**
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   120
     * Returns an {@code IntStream} consisting of the results of applying the
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   121
     * given function to the elements of this stream.
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   122
     *
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   123
     * <p>This is an <a href="package-summary.html#StreamOps">intermediate
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   124
     * operation</a>.
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   125
     *
21339
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   126
     * @param mapper a <a href="package-summary.html#NonInterference">non-interfering</a>,
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   127
     *               <a href="package-summary.html#Statelessness">stateless</a>
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   128
     *               function to apply to each element
17167
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   129
     * @return the new stream
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   130
     */
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   131
    IntStream mapToInt(LongToIntFunction mapper);
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   132
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   133
    /**
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   134
     * Returns a {@code DoubleStream} consisting of the results of applying the
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   135
     * given function to the elements of this stream.
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   136
     *
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   137
     * <p>This is an <a href="package-summary.html#StreamOps">intermediate
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   138
     * operation</a>.
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   139
     *
21339
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   140
     * @param mapper a <a href="package-summary.html#NonInterference">non-interfering</a>,
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   141
     *               <a href="package-summary.html#Statelessness">stateless</a>
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   142
     *               function to apply to each element
17167
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   143
     * @return the new stream
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   144
     */
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   145
    DoubleStream mapToDouble(LongToDoubleFunction mapper);
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   146
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   147
    /**
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   148
     * Returns a stream consisting of the results of replacing each element of
22352
ecbf37860ffa 8032190: It's unclear that flatMap will ensure each stream will be closed.
psandoz
parents: 21846
diff changeset
   149
     * this stream with the contents of a mapped stream produced by applying
ecbf37860ffa 8032190: It's unclear that flatMap will ensure each stream will be closed.
psandoz
parents: 21846
diff changeset
   150
     * the provided mapping function to each element.  Each mapped stream is
ecbf37860ffa 8032190: It's unclear that flatMap will ensure each stream will be closed.
psandoz
parents: 21846
diff changeset
   151
     * {@link java.util.stream.BaseStream#close() closed} after its contents
ecbf37860ffa 8032190: It's unclear that flatMap will ensure each stream will be closed.
psandoz
parents: 21846
diff changeset
   152
     * have been placed into this stream.  (If a mapped stream is {@code null}
ecbf37860ffa 8032190: It's unclear that flatMap will ensure each stream will be closed.
psandoz
parents: 21846
diff changeset
   153
     * an empty stream is used, instead.)
17167
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   154
     *
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   155
     * <p>This is an <a href="package-summary.html#StreamOps">intermediate
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   156
     * operation</a>.
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   157
     *
21339
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   158
     * @param mapper a <a href="package-summary.html#NonInterference">non-interfering</a>,
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   159
     *               <a href="package-summary.html#Statelessness">stateless</a>
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   160
     *               function to apply to each element which produces a
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   161
     *               {@code LongStream} of new values
17167
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   162
     * @return the new stream
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   163
     * @see Stream#flatMap(Function)
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   164
     */
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   165
    LongStream flatMap(LongFunction<? extends LongStream> mapper);
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   166
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   167
    /**
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   168
     * Returns a stream consisting of the distinct elements of this stream.
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   169
     *
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   170
     * <p>This is a <a href="package-summary.html#StreamOps">stateful
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   171
     * intermediate operation</a>.
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   172
     *
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   173
     * @return the new stream
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   174
     */
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   175
    LongStream distinct();
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   176
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   177
    /**
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   178
     * Returns a stream consisting of the elements of this stream in sorted
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   179
     * order.
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   180
     *
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   181
     * <p>This is a <a href="package-summary.html#StreamOps">stateful
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   182
     * intermediate operation</a>.
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   183
     *
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   184
     * @return the new stream
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   185
     */
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   186
    LongStream sorted();
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   187
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   188
    /**
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   189
     * Returns a stream consisting of the elements of this stream, additionally
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   190
     * performing the provided action on each element as elements are consumed
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   191
     * from the resulting stream.
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   192
     *
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   193
     * <p>This is an <a href="package-summary.html#StreamOps">intermediate
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   194
     * operation</a>.
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   195
     *
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   196
     * <p>For parallel stream pipelines, the action may be called at
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   197
     * whatever time and in whatever thread the element is made available by the
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   198
     * upstream operation.  If the action modifies shared state,
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   199
     * it is responsible for providing the required synchronization.
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   200
     *
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   201
     * @apiNote This method exists mainly to support debugging, where you want
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   202
     * to see the elements as they flow past a certain point in a pipeline:
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   203
     * <pre>{@code
21846
c10feb34bc0b 8028516: Java doc error in Int/Long/Double/Stream.peek
psandoz
parents: 21339
diff changeset
   204
     *     LongStream.of(1, 2, 3, 4)
c10feb34bc0b 8028516: Java doc error in Int/Long/Double/Stream.peek
psandoz
parents: 21339
diff changeset
   205
     *         .filter(e -> e > 2)
c10feb34bc0b 8028516: Java doc error in Int/Long/Double/Stream.peek
psandoz
parents: 21339
diff changeset
   206
     *         .peek(e -> System.out.println("Filtered value: " + e))
c10feb34bc0b 8028516: Java doc error in Int/Long/Double/Stream.peek
psandoz
parents: 21339
diff changeset
   207
     *         .map(e -> e * e)
c10feb34bc0b 8028516: Java doc error in Int/Long/Double/Stream.peek
psandoz
parents: 21339
diff changeset
   208
     *         .peek(e -> System.out.println("Mapped value: " + e))
c10feb34bc0b 8028516: Java doc error in Int/Long/Double/Stream.peek
psandoz
parents: 21339
diff changeset
   209
     *         .sum();
17167
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   210
     * }</pre>
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   211
     *
19850
93b368e54c1c 8011916: Spec update for java.util.stream
henryjen
parents: 19800
diff changeset
   212
     * @param action a <a href="package-summary.html#NonInterference">
93b368e54c1c 8011916: Spec update for java.util.stream
henryjen
parents: 19800
diff changeset
   213
     *               non-interfering</a> action to perform on the elements as
93b368e54c1c 8011916: Spec update for java.util.stream
henryjen
parents: 19800
diff changeset
   214
     *               they are consumed from the stream
17167
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   215
     * @return the new stream
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   216
     */
19850
93b368e54c1c 8011916: Spec update for java.util.stream
henryjen
parents: 19800
diff changeset
   217
    LongStream peek(LongConsumer action);
17167
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   218
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   219
    /**
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   220
     * Returns a stream consisting of the elements of this stream, truncated
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   221
     * to be no longer than {@code maxSize} in length.
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   222
     *
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   223
     * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   224
     * stateful intermediate operation</a>.
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   225
     *
20866
36155ee613ef 8025910: rename substream(long) -> skip and remove substream(long,long)
mduigou
parents: 19850
diff changeset
   226
     * @apiNote
36155ee613ef 8025910: rename substream(long) -> skip and remove substream(long,long)
mduigou
parents: 19850
diff changeset
   227
     * While {@code limit()} is generally a cheap operation on sequential
36155ee613ef 8025910: rename substream(long) -> skip and remove substream(long,long)
mduigou
parents: 19850
diff changeset
   228
     * stream pipelines, it can be quite expensive on ordered parallel pipelines,
36155ee613ef 8025910: rename substream(long) -> skip and remove substream(long,long)
mduigou
parents: 19850
diff changeset
   229
     * especially for large values of {@code maxSize}, since {@code limit(n)}
36155ee613ef 8025910: rename substream(long) -> skip and remove substream(long,long)
mduigou
parents: 19850
diff changeset
   230
     * is constrained to return not just any <em>n</em> elements, but the
36155ee613ef 8025910: rename substream(long) -> skip and remove substream(long,long)
mduigou
parents: 19850
diff changeset
   231
     * <em>first n</em> elements in the encounter order.  Using an unordered
36155ee613ef 8025910: rename substream(long) -> skip and remove substream(long,long)
mduigou
parents: 19850
diff changeset
   232
     * stream source (such as {@link #generate(LongSupplier)}) or removing the
36155ee613ef 8025910: rename substream(long) -> skip and remove substream(long,long)
mduigou
parents: 19850
diff changeset
   233
     * ordering constraint with {@link #unordered()} may result in significant
36155ee613ef 8025910: rename substream(long) -> skip and remove substream(long,long)
mduigou
parents: 19850
diff changeset
   234
     * speedups of {@code limit()} in parallel pipelines, if the semantics of
36155ee613ef 8025910: rename substream(long) -> skip and remove substream(long,long)
mduigou
parents: 19850
diff changeset
   235
     * your situation permit.  If consistency with encounter order is required,
36155ee613ef 8025910: rename substream(long) -> skip and remove substream(long,long)
mduigou
parents: 19850
diff changeset
   236
     * and you are experiencing poor performance or memory utilization with
36155ee613ef 8025910: rename substream(long) -> skip and remove substream(long,long)
mduigou
parents: 19850
diff changeset
   237
     * {@code limit()} in parallel pipelines, switching to sequential execution
36155ee613ef 8025910: rename substream(long) -> skip and remove substream(long,long)
mduigou
parents: 19850
diff changeset
   238
     * with {@link #sequential()} may improve performance.
36155ee613ef 8025910: rename substream(long) -> skip and remove substream(long,long)
mduigou
parents: 19850
diff changeset
   239
     *
17167
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   240
     * @param maxSize the number of elements the stream should be limited to
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   241
     * @return the new stream
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   242
     * @throws IllegalArgumentException if {@code maxSize} is negative
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   243
     */
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   244
    LongStream limit(long maxSize);
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   245
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   246
    /**
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   247
     * Returns a stream consisting of the remaining elements of this stream
20866
36155ee613ef 8025910: rename substream(long) -> skip and remove substream(long,long)
mduigou
parents: 19850
diff changeset
   248
     * after discarding the first {@code n} elements of the stream.
36155ee613ef 8025910: rename substream(long) -> skip and remove substream(long,long)
mduigou
parents: 19850
diff changeset
   249
     * If this stream contains fewer than {@code n} elements then an
17167
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   250
     * empty stream will be returned.
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   251
     *
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   252
     * <p>This is a <a href="package-summary.html#StreamOps">stateful
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   253
     * intermediate operation</a>.
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   254
     *
20866
36155ee613ef 8025910: rename substream(long) -> skip and remove substream(long,long)
mduigou
parents: 19850
diff changeset
   255
     * @apiNote
36155ee613ef 8025910: rename substream(long) -> skip and remove substream(long,long)
mduigou
parents: 19850
diff changeset
   256
     * While {@code skip()} is generally a cheap operation on sequential
36155ee613ef 8025910: rename substream(long) -> skip and remove substream(long,long)
mduigou
parents: 19850
diff changeset
   257
     * stream pipelines, it can be quite expensive on ordered parallel pipelines,
36155ee613ef 8025910: rename substream(long) -> skip and remove substream(long,long)
mduigou
parents: 19850
diff changeset
   258
     * especially for large values of {@code n}, since {@code skip(n)}
36155ee613ef 8025910: rename substream(long) -> skip and remove substream(long,long)
mduigou
parents: 19850
diff changeset
   259
     * is constrained to skip not just any <em>n</em> elements, but the
36155ee613ef 8025910: rename substream(long) -> skip and remove substream(long,long)
mduigou
parents: 19850
diff changeset
   260
     * <em>first n</em> elements in the encounter order.  Using an unordered
36155ee613ef 8025910: rename substream(long) -> skip and remove substream(long,long)
mduigou
parents: 19850
diff changeset
   261
     * stream source (such as {@link #generate(LongSupplier)}) or removing the
36155ee613ef 8025910: rename substream(long) -> skip and remove substream(long,long)
mduigou
parents: 19850
diff changeset
   262
     * ordering constraint with {@link #unordered()} may result in significant
36155ee613ef 8025910: rename substream(long) -> skip and remove substream(long,long)
mduigou
parents: 19850
diff changeset
   263
     * speedups of {@code skip()} in parallel pipelines, if the semantics of
36155ee613ef 8025910: rename substream(long) -> skip and remove substream(long,long)
mduigou
parents: 19850
diff changeset
   264
     * your situation permit.  If consistency with encounter order is required,
36155ee613ef 8025910: rename substream(long) -> skip and remove substream(long,long)
mduigou
parents: 19850
diff changeset
   265
     * and you are experiencing poor performance or memory utilization with
36155ee613ef 8025910: rename substream(long) -> skip and remove substream(long,long)
mduigou
parents: 19850
diff changeset
   266
     * {@code skip()} in parallel pipelines, switching to sequential execution
36155ee613ef 8025910: rename substream(long) -> skip and remove substream(long,long)
mduigou
parents: 19850
diff changeset
   267
     * with {@link #sequential()} may improve performance.
36155ee613ef 8025910: rename substream(long) -> skip and remove substream(long,long)
mduigou
parents: 19850
diff changeset
   268
     *
36155ee613ef 8025910: rename substream(long) -> skip and remove substream(long,long)
mduigou
parents: 19850
diff changeset
   269
     * @param n the number of leading elements to skip
17167
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   270
     * @return the new stream
20866
36155ee613ef 8025910: rename substream(long) -> skip and remove substream(long,long)
mduigou
parents: 19850
diff changeset
   271
     * @throws IllegalArgumentException if {@code n} is negative
17167
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   272
     */
20866
36155ee613ef 8025910: rename substream(long) -> skip and remove substream(long,long)
mduigou
parents: 19850
diff changeset
   273
    LongStream skip(long n);
17167
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   274
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   275
    /**
31644
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   276
     * Returns, if this stream is ordered, a stream consisting of the longest
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   277
     * prefix of elements taken from this stream that match the given predicate.
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   278
     * Otherwise returns, if this stream is unordered, a stream consisting of a
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   279
     * subset of elements taken from this stream that match the given predicate.
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   280
     *
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   281
     * <p>If this stream is ordered then the longest prefix is a contiguous
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   282
     * sequence of elements of this stream that match the given predicate.  The
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   283
     * first element of the sequence is the first element of this stream, and
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   284
     * the element immediately following the last element of the sequence does
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   285
     * not match the given predicate.
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   286
     *
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   287
     * <p>If this stream is unordered, and some (but not all) elements of this
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   288
     * stream match the given predicate, then the behavior of this operation is
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   289
     * nondeterministic; it is free to take any subset of matching elements
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   290
     * (which includes the empty set).
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   291
     *
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   292
     * <p>Independent of whether this stream is ordered or unordered if all
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   293
     * elements of this stream match the given predicate then this operation
32002
e378c0dc767e 8130828: Fix some typos and omissions in the the j.u.stream JavaDoc
psandoz
parents: 31644
diff changeset
   294
     * takes all elements (the result is the same as the input), or if no
31644
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   295
     * elements of the stream match the given predicate then no elements are
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   296
     * taken (the result is an empty stream).
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   297
     *
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   298
     * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   299
     * stateful intermediate operation</a>.
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   300
     *
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   301
     * @implSpec
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   302
     * The default implementation obtains the {@link #spliterator() spliterator}
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   303
     * of this stream, wraps that spliterator so as to support the semantics
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   304
     * of this operation on traversal, and returns a new stream associated with
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   305
     * the wrapped spliterator.  The returned stream preserves the execution
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   306
     * characteristics of this stream (namely parallel or sequential execution
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   307
     * as per {@link #isParallel()}) but the wrapped spliterator may choose to
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   308
     * not support splitting.  When the returned stream is closed, the close
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   309
     * handlers for both the returned and this stream are invoked.
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   310
     *
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   311
     * @apiNote
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   312
     * While {@code takeWhile()} is generally a cheap operation on sequential
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   313
     * stream pipelines, it can be quite expensive on ordered parallel
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   314
     * pipelines, since the operation is constrained to return not just any
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   315
     * valid prefix, but the longest prefix of elements in the encounter order.
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   316
     * Using an unordered stream source (such as
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   317
     * {@link #generate(LongSupplier)}) or removing the ordering constraint with
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   318
     * {@link #unordered()} may result in significant speedups of
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   319
     * {@code takeWhile()} in parallel pipelines, if the semantics of your
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   320
     * situation permit.  If consistency with encounter order is required, and
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   321
     * you are experiencing poor performance or memory utilization with
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   322
     * {@code takeWhile()} in parallel pipelines, switching to sequential
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   323
     * execution with {@link #sequential()} may improve performance.
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   324
     *
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   325
     * @param predicate a <a href="package-summary.html#NonInterference">non-interfering</a>,
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   326
     *                  <a href="package-summary.html#Statelessness">stateless</a>
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   327
     *                  predicate to apply to elements to determine the longest
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   328
     *                  prefix of elements.
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   329
     * @return the new stream
32002
e378c0dc767e 8130828: Fix some typos and omissions in the the j.u.stream JavaDoc
psandoz
parents: 31644
diff changeset
   330
     * @since 1.9
31644
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   331
     */
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   332
    default LongStream takeWhile(LongPredicate predicate) {
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   333
        Objects.requireNonNull(predicate);
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   334
        // Reuses the unordered spliterator, which, when encounter is present,
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   335
        // is safe to use as long as it configured not to split
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   336
        return StreamSupport.longStream(
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   337
                new WhileOps.UnorderedWhileSpliterator.OfLong.Taking(spliterator(), true, predicate),
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   338
                isParallel()).onClose(this::close);
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   339
    }
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   340
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   341
    /**
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   342
     * Returns, if this stream is ordered, a stream consisting of the remaining
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   343
     * elements of this stream after dropping the longest prefix of elements
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   344
     * that match the given predicate.  Otherwise returns, if this stream is
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   345
     * unordered, a stream consisting of the remaining elements of this stream
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   346
     * after dropping a subset of elements that match the given predicate.
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   347
     *
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   348
     * <p>If this stream is ordered then the longest prefix is a contiguous
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   349
     * sequence of elements of this stream that match the given predicate.  The
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   350
     * first element of the sequence is the first element of this stream, and
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   351
     * the element immediately following the last element of the sequence does
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   352
     * not match the given predicate.
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   353
     *
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   354
     * <p>If this stream is unordered, and some (but not all) elements of this
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   355
     * stream match the given predicate, then the behavior of this operation is
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   356
     * nondeterministic; it is free to drop any subset of matching elements
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   357
     * (which includes the empty set).
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   358
     *
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   359
     * <p>Independent of whether this stream is ordered or unordered if all
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   360
     * elements of this stream match the given predicate then this operation
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   361
     * drops all elements (the result is an empty stream), or if no elements of
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   362
     * the stream match the given predicate then no elements are dropped (the
32002
e378c0dc767e 8130828: Fix some typos and omissions in the the j.u.stream JavaDoc
psandoz
parents: 31644
diff changeset
   363
     * result is the same as the input).
31644
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   364
     *
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   365
     * <p>This is a <a href="package-summary.html#StreamOps">stateful
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   366
     * intermediate operation</a>.
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   367
     *
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   368
     * @implSpec
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   369
     * The default implementation obtains the {@link #spliterator() spliterator}
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   370
     * of this stream, wraps that spliterator so as to support the semantics
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   371
     * of this operation on traversal, and returns a new stream associated with
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   372
     * the wrapped spliterator.  The returned stream preserves the execution
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   373
     * characteristics of this stream (namely parallel or sequential execution
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   374
     * as per {@link #isParallel()}) but the wrapped spliterator may choose to
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   375
     * not support splitting.  When the returned stream is closed, the close
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   376
     * handlers for both the returned and this stream are invoked.
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   377
     *
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   378
     * @apiNote
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   379
     * While {@code dropWhile()} is generally a cheap operation on sequential
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   380
     * stream pipelines, it can be quite expensive on ordered parallel
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   381
     * pipelines, since the operation is constrained to return not just any
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   382
     * valid prefix, but the longest prefix of elements in the encounter order.
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   383
     * Using an unordered stream source (such as
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   384
     * {@link #generate(LongSupplier)}) or removing the ordering constraint with
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   385
     * {@link #unordered()} may result in significant speedups of
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   386
     * {@code dropWhile()} in parallel pipelines, if the semantics of your
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   387
     * situation permit.  If consistency with encounter order is required, and
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   388
     * you are experiencing poor performance or memory utilization with
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   389
     * {@code dropWhile()} in parallel pipelines, switching to sequential
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   390
     * execution with {@link #sequential()} may improve performance.
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   391
     *
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   392
     * @param predicate a <a href="package-summary.html#NonInterference">non-interfering</a>,
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   393
     *                  <a href="package-summary.html#Statelessness">stateless</a>
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   394
     *                  predicate to apply to elements to determine the longest
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   395
     *                  prefix of elements.
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   396
     * @return the new stream
32002
e378c0dc767e 8130828: Fix some typos and omissions in the the j.u.stream JavaDoc
psandoz
parents: 31644
diff changeset
   397
     * @since 1.9
31644
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   398
     */
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   399
    default LongStream dropWhile(LongPredicate predicate) {
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   400
        Objects.requireNonNull(predicate);
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   401
        // Reuses the unordered spliterator, which, when encounter is present,
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   402
        // is safe to use as long as it configured not to split
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   403
        return StreamSupport.longStream(
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   404
                new WhileOps.UnorderedWhileSpliterator.OfLong.Dropping(spliterator(), true, predicate),
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   405
                isParallel()).onClose(this::close);
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   406
    }
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   407
dbca10d053fd 8071597: Add Stream dropWhile and takeWhile operations
psandoz
parents: 29489
diff changeset
   408
    /**
17167
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   409
     * Performs an action for each element of this stream.
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   410
     *
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   411
     * <p>This is a <a href="package-summary.html#StreamOps">terminal
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   412
     * operation</a>.
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   413
     *
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   414
     * <p>For parallel stream pipelines, this operation does <em>not</em>
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   415
     * guarantee to respect the encounter order of the stream, as doing so
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   416
     * would sacrifice the benefit of parallelism.  For any given element, the
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   417
     * action may be performed at whatever time and in whatever thread the
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   418
     * library chooses.  If the action accesses shared state, it is
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   419
     * responsible for providing the required synchronization.
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   420
     *
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   421
     * @param action a <a href="package-summary.html#NonInterference">
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   422
     *               non-interfering</a> action to perform on the elements
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   423
     */
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   424
    void forEach(LongConsumer action);
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   425
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   426
    /**
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   427
     * Performs an action for each element of this stream, guaranteeing that
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   428
     * each element is processed in encounter order for streams that have a
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   429
     * defined encounter order.
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   430
     *
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   431
     * <p>This is a <a href="package-summary.html#StreamOps">terminal
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   432
     * operation</a>.
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   433
     *
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   434
     * @param action a <a href="package-summary.html#NonInterference">
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   435
     *               non-interfering</a> action to perform on the elements
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   436
     * @see #forEach(LongConsumer)
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   437
     */
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   438
    void forEachOrdered(LongConsumer action);
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   439
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   440
    /**
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   441
     * Returns an array containing the elements of this stream.
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   442
     *
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   443
     * <p>This is a <a href="package-summary.html#StreamOps">terminal
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   444
     * operation</a>.
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   445
     *
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   446
     * @return an array containing the elements of this stream
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   447
     */
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   448
    long[] toArray();
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   449
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   450
    /**
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   451
     * Performs a <a href="package-summary.html#Reduction">reduction</a> on the
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   452
     * elements of this stream, using the provided identity value and an
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   453
     * <a href="package-summary.html#Associativity">associative</a>
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   454
     * accumulation function, and returns the reduced value.  This is equivalent
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   455
     * to:
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   456
     * <pre>{@code
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   457
     *     long result = identity;
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   458
     *     for (long element : this stream)
22996
0ce70f4ef909 8029944: Primitive Stream reduce method documentation pseudo code misidentifies apply method
michaelm
parents: 22352
diff changeset
   459
     *         result = accumulator.applyAsLong(result, element)
17167
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   460
     *     return result;
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   461
     * }</pre>
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   462
     *
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   463
     * but is not constrained to execute sequentially.
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   464
     *
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   465
     * <p>The {@code identity} value must be an identity for the accumulator
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   466
     * function. This means that for all {@code x},
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   467
     * {@code accumulator.apply(identity, x)} is equal to {@code x}.
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   468
     * The {@code accumulator} function must be an
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   469
     * <a href="package-summary.html#Associativity">associative</a> function.
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   470
     *
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   471
     * <p>This is a <a href="package-summary.html#StreamOps">terminal
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   472
     * operation</a>.
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   473
     *
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   474
     * @apiNote Sum, min, max, and average are all special cases of reduction.
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   475
     * Summing a stream of numbers can be expressed as:
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   476
     *
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   477
     * <pre>{@code
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   478
     *     long sum = integers.reduce(0, (a, b) -> a+b);
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   479
     * }</pre>
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   480
     *
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   481
     * or more compactly:
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   482
     *
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   483
     * <pre>{@code
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   484
     *     long sum = integers.reduce(0, Long::sum);
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   485
     * }</pre>
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   486
     *
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   487
     * <p>While this may seem a more roundabout way to perform an aggregation
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   488
     * compared to simply mutating a running total in a loop, reduction
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   489
     * operations parallelize more gracefully, without needing additional
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   490
     * synchronization and with greatly reduced risk of data races.
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   491
     *
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   492
     * @param identity the identity value for the accumulating function
21339
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   493
     * @param op an <a href="package-summary.html#Associativity">associative</a>,
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   494
     *           <a href="package-summary.html#NonInterference">non-interfering</a>,
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   495
     *           <a href="package-summary.html#Statelessness">stateless</a>
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   496
     *           function for combining two values
17167
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   497
     * @return the result of the reduction
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   498
     * @see #sum()
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   499
     * @see #min()
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   500
     * @see #max()
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   501
     * @see #average()
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   502
     */
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   503
    long reduce(long identity, LongBinaryOperator op);
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   504
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   505
    /**
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   506
     * Performs a <a href="package-summary.html#Reduction">reduction</a> on the
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   507
     * elements of this stream, using an
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   508
     * <a href="package-summary.html#Associativity">associative</a> accumulation
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   509
     * function, and returns an {@code OptionalLong} describing the reduced value,
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   510
     * if any. This is equivalent to:
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   511
     * <pre>{@code
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   512
     *     boolean foundAny = false;
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   513
     *     long result = null;
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   514
     *     for (long element : this stream) {
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   515
     *         if (!foundAny) {
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   516
     *             foundAny = true;
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   517
     *             result = element;
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   518
     *         }
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   519
     *         else
22996
0ce70f4ef909 8029944: Primitive Stream reduce method documentation pseudo code misidentifies apply method
michaelm
parents: 22352
diff changeset
   520
     *             result = accumulator.applyAsLong(result, element);
17167
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   521
     *     }
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   522
     *     return foundAny ? OptionalLong.of(result) : OptionalLong.empty();
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   523
     * }</pre>
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   524
     *
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   525
     * but is not constrained to execute sequentially.
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   526
     *
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   527
     * <p>The {@code accumulator} function must be an
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   528
     * <a href="package-summary.html#Associativity">associative</a> function.
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   529
     *
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   530
     * <p>This is a <a href="package-summary.html#StreamOps">terminal
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   531
     * operation</a>.
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   532
     *
21339
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   533
     * @param op an <a href="package-summary.html#Associativity">associative</a>,
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   534
     *           <a href="package-summary.html#NonInterference">non-interfering</a>,
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   535
     *           <a href="package-summary.html#Statelessness">stateless</a>
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   536
     *           function for combining two values
17167
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   537
     * @return the result of the reduction
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   538
     * @see #reduce(long, LongBinaryOperator)
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   539
     */
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   540
    OptionalLong reduce(LongBinaryOperator op);
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   541
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   542
    /**
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   543
     * Performs a <a href="package-summary.html#MutableReduction">mutable
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   544
     * reduction</a> operation on the elements of this stream.  A mutable
19850
93b368e54c1c 8011916: Spec update for java.util.stream
henryjen
parents: 19800
diff changeset
   545
     * reduction is one in which the reduced value is a mutable result container,
17167
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   546
     * such as an {@code ArrayList}, and elements are incorporated by updating
19850
93b368e54c1c 8011916: Spec update for java.util.stream
henryjen
parents: 19800
diff changeset
   547
     * the state of the result rather than by replacing the result.  This
17167
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   548
     * produces a result equivalent to:
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   549
     * <pre>{@code
19850
93b368e54c1c 8011916: Spec update for java.util.stream
henryjen
parents: 19800
diff changeset
   550
     *     R result = supplier.get();
17167
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   551
     *     for (long element : this stream)
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   552
     *         accumulator.accept(result, element);
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   553
     *     return result;
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   554
     * }</pre>
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   555
     *
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   556
     * <p>Like {@link #reduce(long, LongBinaryOperator)}, {@code collect} operations
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   557
     * can be parallelized without requiring additional synchronization.
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   558
     *
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   559
     * <p>This is a <a href="package-summary.html#StreamOps">terminal
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   560
     * operation</a>.
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   561
     *
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   562
     * @param <R> type of the result
19850
93b368e54c1c 8011916: Spec update for java.util.stream
henryjen
parents: 19800
diff changeset
   563
     * @param supplier a function that creates a new result container. For a
93b368e54c1c 8011916: Spec update for java.util.stream
henryjen
parents: 19800
diff changeset
   564
     *                 parallel execution, this function may be called
93b368e54c1c 8011916: Spec update for java.util.stream
henryjen
parents: 19800
diff changeset
   565
     *                 multiple times and must return a fresh value each time.
21339
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   566
     * @param accumulator an <a href="package-summary.html#Associativity">associative</a>,
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   567
     *                    <a href="package-summary.html#NonInterference">non-interfering</a>,
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   568
     *                    <a href="package-summary.html#Statelessness">stateless</a>
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   569
     *                    function for incorporating an additional element into a result
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   570
     * @param combiner an <a href="package-summary.html#Associativity">associative</a>,
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   571
     *                    <a href="package-summary.html#NonInterference">non-interfering</a>,
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   572
     *                    <a href="package-summary.html#Statelessness">stateless</a>
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   573
     *                    function for combining two values, which must be
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   574
     *                    compatible with the accumulator function
17167
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   575
     * @return the result of the reduction
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   576
     * @see Stream#collect(Supplier, BiConsumer, BiConsumer)
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   577
     */
19850
93b368e54c1c 8011916: Spec update for java.util.stream
henryjen
parents: 19800
diff changeset
   578
    <R> R collect(Supplier<R> supplier,
17167
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   579
                  ObjLongConsumer<R> accumulator,
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   580
                  BiConsumer<R, R> combiner);
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   581
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   582
    /**
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   583
     * Returns the sum of elements in this stream.  This is a special case
19850
93b368e54c1c 8011916: Spec update for java.util.stream
henryjen
parents: 19800
diff changeset
   584
     * of a <a href="package-summary.html#Reduction">reduction</a>
17167
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   585
     * and is equivalent to:
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   586
     * <pre>{@code
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   587
     *     return reduce(0, Long::sum);
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   588
     * }</pre>
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   589
     *
19850
93b368e54c1c 8011916: Spec update for java.util.stream
henryjen
parents: 19800
diff changeset
   590
     * <p>This is a <a href="package-summary.html#StreamOps">terminal
93b368e54c1c 8011916: Spec update for java.util.stream
henryjen
parents: 19800
diff changeset
   591
     * operation</a>.
93b368e54c1c 8011916: Spec update for java.util.stream
henryjen
parents: 19800
diff changeset
   592
     *
17167
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   593
     * @return the sum of elements in this stream
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   594
     */
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   595
    long sum();
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   596
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   597
    /**
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   598
     * Returns an {@code OptionalLong} describing the minimum element of this
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   599
     * stream, or an empty optional if this stream is empty.  This is a special
19850
93b368e54c1c 8011916: Spec update for java.util.stream
henryjen
parents: 19800
diff changeset
   600
     * case of a <a href="package-summary.html#Reduction">reduction</a>
17167
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   601
     * and is equivalent to:
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   602
     * <pre>{@code
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   603
     *     return reduce(Long::min);
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   604
     * }</pre>
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   605
     *
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   606
     * <p>This is a <a href="package-summary.html#StreamOps">terminal operation</a>.
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   607
     *
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   608
     * @return an {@code OptionalLong} containing the minimum element of this
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   609
     * stream, or an empty {@code OptionalLong} if the stream is empty
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   610
     */
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   611
    OptionalLong min();
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   612
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   613
    /**
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   614
     * Returns an {@code OptionalLong} describing the maximum element of this
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   615
     * stream, or an empty optional if this stream is empty.  This is a special
19850
93b368e54c1c 8011916: Spec update for java.util.stream
henryjen
parents: 19800
diff changeset
   616
     * case of a <a href="package-summary.html#Reduction">reduction</a>
17167
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   617
     * and is equivalent to:
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   618
     * <pre>{@code
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   619
     *     return reduce(Long::max);
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   620
     * }</pre>
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   621
     *
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   622
     * <p>This is a <a href="package-summary.html#StreamOps">terminal
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   623
     * operation</a>.
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   624
     *
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   625
     * @return an {@code OptionalLong} containing the maximum element of this
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   626
     * stream, or an empty {@code OptionalLong} if the stream is empty
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   627
     */
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   628
    OptionalLong max();
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   629
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   630
    /**
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   631
     * Returns the count of elements in this stream.  This is a special case of
19850
93b368e54c1c 8011916: Spec update for java.util.stream
henryjen
parents: 19800
diff changeset
   632
     * a <a href="package-summary.html#Reduction">reduction</a> and is
17167
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   633
     * equivalent to:
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   634
     * <pre>{@code
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   635
     *     return map(e -> 1L).sum();
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   636
     * }</pre>
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   637
     *
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   638
     * <p>This is a <a href="package-summary.html#StreamOps">terminal operation</a>.
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   639
     *
29489
fe7624d92790 8067969: Optimize Stream.count for SIZED Streams
psandoz
parents: 29103
diff changeset
   640
     * @apiNote
fe7624d92790 8067969: Optimize Stream.count for SIZED Streams
psandoz
parents: 29103
diff changeset
   641
     * An implementation may choose to not execute the stream pipeline (either
fe7624d92790 8067969: Optimize Stream.count for SIZED Streams
psandoz
parents: 29103
diff changeset
   642
     * sequentially or in parallel) if it is capable of computing the count
fe7624d92790 8067969: Optimize Stream.count for SIZED Streams
psandoz
parents: 29103
diff changeset
   643
     * directly from the stream source.  In such cases no source elements will
fe7624d92790 8067969: Optimize Stream.count for SIZED Streams
psandoz
parents: 29103
diff changeset
   644
     * be traversed and no intermediate operations will be evaluated.
fe7624d92790 8067969: Optimize Stream.count for SIZED Streams
psandoz
parents: 29103
diff changeset
   645
     * Behavioral parameters with side-effects, which are strongly discouraged
fe7624d92790 8067969: Optimize Stream.count for SIZED Streams
psandoz
parents: 29103
diff changeset
   646
     * except for harmless cases such as debugging, may be affected.  For
fe7624d92790 8067969: Optimize Stream.count for SIZED Streams
psandoz
parents: 29103
diff changeset
   647
     * example, consider the following stream:
fe7624d92790 8067969: Optimize Stream.count for SIZED Streams
psandoz
parents: 29103
diff changeset
   648
     * <pre>{@code
fe7624d92790 8067969: Optimize Stream.count for SIZED Streams
psandoz
parents: 29103
diff changeset
   649
     *     LongStream s = LongStream.of(1, 2, 3, 4);
fe7624d92790 8067969: Optimize Stream.count for SIZED Streams
psandoz
parents: 29103
diff changeset
   650
     *     long count = s.peek(System.out::println).count();
fe7624d92790 8067969: Optimize Stream.count for SIZED Streams
psandoz
parents: 29103
diff changeset
   651
     * }</pre>
fe7624d92790 8067969: Optimize Stream.count for SIZED Streams
psandoz
parents: 29103
diff changeset
   652
     * The number of elements covered by the stream source is known and the
fe7624d92790 8067969: Optimize Stream.count for SIZED Streams
psandoz
parents: 29103
diff changeset
   653
     * intermediate operation, {@code peek}, does not inject into or remove
fe7624d92790 8067969: Optimize Stream.count for SIZED Streams
psandoz
parents: 29103
diff changeset
   654
     * elements from the stream (as may be the case for {@code flatMap} or
fe7624d92790 8067969: Optimize Stream.count for SIZED Streams
psandoz
parents: 29103
diff changeset
   655
     * {@code filter} operations).  Thus the count is 4 and there is no need to
fe7624d92790 8067969: Optimize Stream.count for SIZED Streams
psandoz
parents: 29103
diff changeset
   656
     * execute the pipeline and, as a side-effect, print out the elements.
fe7624d92790 8067969: Optimize Stream.count for SIZED Streams
psandoz
parents: 29103
diff changeset
   657
     *
17167
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   658
     * @return the count of elements in this stream
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   659
     */
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   660
    long count();
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   661
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   662
    /**
19214
e5901820c3c1 8015318: Extend Collector with 'finish' operation
briangoetz
parents: 18825
diff changeset
   663
     * Returns an {@code OptionalDouble} describing the arithmetic mean of elements of
17167
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   664
     * this stream, or an empty optional if this stream is empty.  This is a
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   665
     * special case of a
19850
93b368e54c1c 8011916: Spec update for java.util.stream
henryjen
parents: 19800
diff changeset
   666
     * <a href="package-summary.html#Reduction">reduction</a>.
93b368e54c1c 8011916: Spec update for java.util.stream
henryjen
parents: 19800
diff changeset
   667
     *
93b368e54c1c 8011916: Spec update for java.util.stream
henryjen
parents: 19800
diff changeset
   668
     * <p>This is a <a href="package-summary.html#StreamOps">terminal
93b368e54c1c 8011916: Spec update for java.util.stream
henryjen
parents: 19800
diff changeset
   669
     * operation</a>.
17167
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   670
     *
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   671
     * @return an {@code OptionalDouble} containing the average element of this
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   672
     * stream, or an empty optional if the stream is empty
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   673
     */
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   674
    OptionalDouble average();
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   675
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   676
    /**
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   677
     * Returns a {@code LongSummaryStatistics} describing various summary data
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   678
     * about the elements of this stream.  This is a special case of a
19850
93b368e54c1c 8011916: Spec update for java.util.stream
henryjen
parents: 19800
diff changeset
   679
     * <a href="package-summary.html#Reduction">reduction</a>.
93b368e54c1c 8011916: Spec update for java.util.stream
henryjen
parents: 19800
diff changeset
   680
     *
93b368e54c1c 8011916: Spec update for java.util.stream
henryjen
parents: 19800
diff changeset
   681
     * <p>This is a <a href="package-summary.html#StreamOps">terminal
93b368e54c1c 8011916: Spec update for java.util.stream
henryjen
parents: 19800
diff changeset
   682
     * operation</a>.
17167
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   683
     *
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   684
     * @return a {@code LongSummaryStatistics} describing various summary data
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   685
     * about the elements of this stream
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   686
     */
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   687
    LongSummaryStatistics summaryStatistics();
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   688
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   689
    /**
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   690
     * Returns whether any elements of this stream match the provided
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   691
     * predicate.  May not evaluate the predicate on all elements if not
21339
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   692
     * necessary for determining the result.  If the stream is empty then
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   693
     * {@code false} is returned and the predicate is not evaluated.
17167
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   694
     *
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   695
     * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   696
     * terminal operation</a>.
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   697
     *
21339
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   698
     * @apiNote
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   699
     * This method evaluates the <em>existential quantification</em> of the
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   700
     * predicate over the elements of the stream (for some x P(x)).
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   701
     *
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   702
     * @param predicate a <a href="package-summary.html#NonInterference">non-interfering</a>,
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   703
     *                  <a href="package-summary.html#Statelessness">stateless</a>
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   704
     *                  predicate to apply to elements of this stream
17167
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   705
     * @return {@code true} if any elements of the stream match the provided
21339
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   706
     * predicate, otherwise {@code false}
17167
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   707
     */
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   708
    boolean anyMatch(LongPredicate predicate);
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   709
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   710
    /**
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   711
     * Returns whether all elements of this stream match the provided predicate.
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   712
     * May not evaluate the predicate on all elements if not necessary for
21339
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   713
     * determining the result.  If the stream is empty then {@code true} is
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   714
     * returned and the predicate is not evaluated.
17167
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   715
     *
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   716
     * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   717
     * terminal operation</a>.
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   718
     *
21339
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   719
     * @apiNote
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   720
     * This method evaluates the <em>universal quantification</em> of the
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   721
     * predicate over the elements of the stream (for all x P(x)).  If the
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   722
     * stream is empty, the quantification is said to be <em>vacuously
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   723
     * satisfied</em> and is always {@code true} (regardless of P(x)).
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   724
     *
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   725
     * @param predicate a <a href="package-summary.html#NonInterference">non-interfering</a>,
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   726
     *                  <a href="package-summary.html#Statelessness">stateless</a>
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   727
     *                  predicate to apply to elements of this stream
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   728
     * @return {@code true} if either all elements of the stream match the
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   729
     * provided predicate or the stream is empty, otherwise {@code false}
17167
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   730
     */
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   731
    boolean allMatch(LongPredicate predicate);
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   732
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   733
    /**
21339
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   734
     * Returns whether no elements of this stream match the provided predicate.
17167
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   735
     * May not evaluate the predicate on all elements if not necessary for
21339
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   736
     * determining the result.  If the stream is empty then {@code true} is
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   737
     * returned and the predicate is not evaluated.
17167
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   738
     *
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   739
     * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   740
     * terminal operation</a>.
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   741
     *
21339
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   742
     * @apiNote
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   743
     * This method evaluates the <em>universal quantification</em> of the
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   744
     * negated predicate over the elements of the stream (for all x ~P(x)).  If
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   745
     * the stream is empty, the quantification is said to be vacuously satisfied
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   746
     * and is always {@code true}, regardless of P(x).
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   747
     *
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   748
     * @param predicate a <a href="package-summary.html#NonInterference">non-interfering</a>,
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   749
     *                  <a href="package-summary.html#Statelessness">stateless</a>
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   750
     *                  predicate to apply to elements of this stream
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   751
     * @return {@code true} if either no elements of the stream match the
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   752
     * provided predicate or the stream is empty, otherwise {@code false}
17167
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   753
     */
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   754
    boolean noneMatch(LongPredicate predicate);
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   755
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   756
    /**
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   757
     * Returns an {@link OptionalLong} describing the first element of this
19850
93b368e54c1c 8011916: Spec update for java.util.stream
henryjen
parents: 19800
diff changeset
   758
     * stream, or an empty {@code OptionalLong} if the stream is empty.  If the
93b368e54c1c 8011916: Spec update for java.util.stream
henryjen
parents: 19800
diff changeset
   759
     * stream has no encounter order, then any element may be returned.
17167
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   760
     *
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   761
     * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   762
     * terminal operation</a>.
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   763
     *
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   764
     * @return an {@code OptionalLong} describing the first element of this
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   765
     * stream, or an empty {@code OptionalLong} if the stream is empty
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   766
     */
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   767
    OptionalLong findFirst();
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   768
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   769
    /**
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   770
     * Returns an {@link OptionalLong} describing some element of the stream, or
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   771
     * an empty {@code OptionalLong} if the stream is empty.
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   772
     *
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   773
     * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   774
     * terminal operation</a>.
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   775
     *
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   776
     * <p>The behavior of this operation is explicitly nondeterministic; it is
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   777
     * free to select any element in the stream.  This is to allow for maximal
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   778
     * performance in parallel operations; the cost is that multiple invocations
19850
93b368e54c1c 8011916: Spec update for java.util.stream
henryjen
parents: 19800
diff changeset
   779
     * on the same source may not return the same result.  (If a stable result
93b368e54c1c 8011916: Spec update for java.util.stream
henryjen
parents: 19800
diff changeset
   780
     * is desired, use {@link #findFirst()} instead.)
17167
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   781
     *
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   782
     * @return an {@code OptionalLong} describing some element of this stream,
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   783
     * or an empty {@code OptionalLong} if the stream is empty
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   784
     * @see #findFirst()
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   785
     */
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   786
    OptionalLong findAny();
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   787
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   788
    /**
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   789
     * Returns a {@code DoubleStream} consisting of the elements of this stream,
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   790
     * converted to {@code double}.
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   791
     *
19850
93b368e54c1c 8011916: Spec update for java.util.stream
henryjen
parents: 19800
diff changeset
   792
     * <p>This is an <a href="package-summary.html#StreamOps">intermediate
93b368e54c1c 8011916: Spec update for java.util.stream
henryjen
parents: 19800
diff changeset
   793
     * operation</a>.
93b368e54c1c 8011916: Spec update for java.util.stream
henryjen
parents: 19800
diff changeset
   794
     *
17167
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   795
     * @return a {@code DoubleStream} consisting of the elements of this stream,
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   796
     * converted to {@code double}
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   797
     */
18154
5ede18269905 8015798: Rename IntStream.longs/doubles and LongStream.doubles to asXxxStream
psandoz
parents: 17914
diff changeset
   798
    DoubleStream asDoubleStream();
17167
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   799
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   800
    /**
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   801
     * Returns a {@code Stream} consisting of the elements of this stream,
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   802
     * each boxed to a {@code Long}.
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   803
     *
19850
93b368e54c1c 8011916: Spec update for java.util.stream
henryjen
parents: 19800
diff changeset
   804
     * <p>This is an <a href="package-summary.html#StreamOps">intermediate
93b368e54c1c 8011916: Spec update for java.util.stream
henryjen
parents: 19800
diff changeset
   805
     * operation</a>.
93b368e54c1c 8011916: Spec update for java.util.stream
henryjen
parents: 19800
diff changeset
   806
     *
17167
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   807
     * @return a {@code Stream} consistent of the elements of this stream,
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   808
     * each boxed to {@code Long}
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   809
     */
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   810
    Stream<Long> boxed();
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   811
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   812
    @Override
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   813
    LongStream sequential();
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   814
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   815
    @Override
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   816
    LongStream parallel();
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   817
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   818
    @Override
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   819
    PrimitiveIterator.OfLong iterator();
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   820
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   821
    @Override
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
   822
    Spliterator.OfLong spliterator();
17195
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   823
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   824
    // Static factories
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   825
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   826
    /**
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   827
     * Returns a builder for a {@code LongStream}.
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   828
     *
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   829
     * @return a stream builder
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   830
     */
18825
06636235cd12 8020062: Nest StreamBuilder interfaces inside relevant Stream interfaces
henryjen
parents: 18822
diff changeset
   831
    public static Builder builder() {
17195
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   832
        return new Streams.LongStreamBuilderImpl();
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   833
    }
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   834
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   835
    /**
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   836
     * Returns an empty sequential {@code LongStream}.
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   837
     *
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   838
     * @return an empty sequential stream
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   839
     */
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   840
    public static LongStream empty() {
18822
4b6be7c19547 8019395: Consolidate StreamSupport.{stream,parallelStream} into a single method
psandoz
parents: 18820
diff changeset
   841
        return StreamSupport.longStream(Spliterators.emptyLongSpliterator(), false);
17195
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   842
    }
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   843
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   844
    /**
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   845
     * Returns a sequential {@code LongStream} containing a single element.
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   846
     *
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   847
     * @param t the single element
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   848
     * @return a singleton sequential stream
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   849
     */
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   850
    public static LongStream of(long t) {
18822
4b6be7c19547 8019395: Consolidate StreamSupport.{stream,parallelStream} into a single method
psandoz
parents: 18820
diff changeset
   851
        return StreamSupport.longStream(new Streams.LongStreamBuilderImpl(t), false);
17195
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   852
    }
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   853
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   854
    /**
19850
93b368e54c1c 8011916: Spec update for java.util.stream
henryjen
parents: 19800
diff changeset
   855
     * Returns a sequential ordered stream whose elements are the specified values.
17195
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   856
     *
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   857
     * @param values the elements of the new stream
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   858
     * @return the new stream
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   859
     */
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   860
    public static LongStream of(long... values) {
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   861
        return Arrays.stream(values);
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   862
    }
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   863
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   864
    /**
19850
93b368e54c1c 8011916: Spec update for java.util.stream
henryjen
parents: 19800
diff changeset
   865
     * Returns an infinite sequential ordered {@code LongStream} produced by iterative
17195
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   866
     * application of a function {@code f} to an initial element {@code seed},
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   867
     * producing a {@code Stream} consisting of {@code seed}, {@code f(seed)},
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   868
     * {@code f(f(seed))}, etc.
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   869
     *
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   870
     * <p>The first element (position {@code 0}) in the {@code LongStream} will
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   871
     * be the provided {@code seed}.  For {@code n > 0}, the element at position
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   872
     * {@code n}, will be the result of applying the function {@code f} to the
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   873
     * element at position {@code n - 1}.
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   874
     *
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   875
     * @param seed the initial element
25526
d3cbdae6e9f9 8044047: Missing null pointer checks for streams
psandoz
parents: 22996
diff changeset
   876
     * @param f a function to be applied to the previous element to produce
17195
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   877
     *          a new element
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   878
     * @return a new sequential {@code LongStream}
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   879
     */
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   880
    public static LongStream iterate(final long seed, final LongUnaryOperator f) {
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   881
        Objects.requireNonNull(f);
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   882
        final PrimitiveIterator.OfLong iterator = new PrimitiveIterator.OfLong() {
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   883
            long t = seed;
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   884
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   885
            @Override
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   886
            public boolean hasNext() {
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   887
                return true;
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   888
            }
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   889
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   890
            @Override
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   891
            public long nextLong() {
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   892
                long v = t;
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   893
                t = f.applyAsLong(t);
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   894
                return v;
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   895
            }
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   896
        };
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   897
        return StreamSupport.longStream(Spliterators.spliteratorUnknownSize(
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   898
                iterator,
18822
4b6be7c19547 8019395: Consolidate StreamSupport.{stream,parallelStream} into a single method
psandoz
parents: 18820
diff changeset
   899
                Spliterator.ORDERED | Spliterator.IMMUTABLE | Spliterator.NONNULL), false);
17195
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   900
    }
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   901
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   902
    /**
21339
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   903
     * Returns an infinite sequential unordered stream where each element is
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   904
     * generated by the provided {@code LongSupplier}.  This is suitable for
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   905
     * generating constant streams, streams of random elements, etc.
17195
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   906
     *
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   907
     * @param s the {@code LongSupplier} for generated elements
21339
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   908
     * @return a new infinite sequential unordered {@code LongStream}
17195
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   909
     */
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   910
    public static LongStream generate(LongSupplier s) {
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   911
        Objects.requireNonNull(s);
18572
53b8b8c30086 8012987: Optimizations for Stream.limit/substream
psandoz
parents: 18158
diff changeset
   912
        return StreamSupport.longStream(
18822
4b6be7c19547 8019395: Consolidate StreamSupport.{stream,parallelStream} into a single method
psandoz
parents: 18820
diff changeset
   913
                new StreamSpliterators.InfiniteSupplyingSpliterator.OfLong(Long.MAX_VALUE, s), false);
17195
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   914
    }
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   915
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   916
    /**
19850
93b368e54c1c 8011916: Spec update for java.util.stream
henryjen
parents: 19800
diff changeset
   917
     * Returns a sequential ordered {@code LongStream} from {@code startInclusive}
17195
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   918
     * (inclusive) to {@code endExclusive} (exclusive) by an incremental step of
18158
d5a620310f97 8015895: Int/LongStream.range/rangeClosed
psandoz
parents: 18154
diff changeset
   919
     * {@code 1}.
17195
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   920
     *
18158
d5a620310f97 8015895: Int/LongStream.range/rangeClosed
psandoz
parents: 18154
diff changeset
   921
     * @apiNote
d5a620310f97 8015895: Int/LongStream.range/rangeClosed
psandoz
parents: 18154
diff changeset
   922
     * <p>An equivalent sequence of increasing values can be produced
d5a620310f97 8015895: Int/LongStream.range/rangeClosed
psandoz
parents: 18154
diff changeset
   923
     * sequentially using a {@code for} loop as follows:
17195
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   924
     * <pre>{@code
18158
d5a620310f97 8015895: Int/LongStream.range/rangeClosed
psandoz
parents: 18154
diff changeset
   925
     *     for (long i = startInclusive; i < endExclusive ; i++) { ... }
17195
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   926
     * }</pre>
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   927
     *
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   928
     * @param startInclusive the (inclusive) initial value
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   929
     * @param endExclusive the exclusive upper bound
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   930
     * @return a sequential {@code LongStream} for the range of {@code long}
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   931
     *         elements
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   932
     */
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   933
    public static LongStream range(long startInclusive, final long endExclusive) {
18158
d5a620310f97 8015895: Int/LongStream.range/rangeClosed
psandoz
parents: 18154
diff changeset
   934
        if (startInclusive >= endExclusive) {
d5a620310f97 8015895: Int/LongStream.range/rangeClosed
psandoz
parents: 18154
diff changeset
   935
            return empty();
d5a620310f97 8015895: Int/LongStream.range/rangeClosed
psandoz
parents: 18154
diff changeset
   936
        } else if (endExclusive - startInclusive < 0) {
d5a620310f97 8015895: Int/LongStream.range/rangeClosed
psandoz
parents: 18154
diff changeset
   937
            // Size of range > Long.MAX_VALUE
d5a620310f97 8015895: Int/LongStream.range/rangeClosed
psandoz
parents: 18154
diff changeset
   938
            // Split the range in two and concatenate
d5a620310f97 8015895: Int/LongStream.range/rangeClosed
psandoz
parents: 18154
diff changeset
   939
            // Note: if the range is [Long.MIN_VALUE, Long.MAX_VALUE) then
d5a620310f97 8015895: Int/LongStream.range/rangeClosed
psandoz
parents: 18154
diff changeset
   940
            // the lower range, [Long.MIN_VALUE, 0) will be further split in two
18820
a87cdd6a8834 8015315: Stream.concat methods
mduigou
parents: 18572
diff changeset
   941
            long m = startInclusive + Long.divideUnsigned(endExclusive - startInclusive, 2) + 1;
a87cdd6a8834 8015315: Stream.concat methods
mduigou
parents: 18572
diff changeset
   942
            return concat(range(startInclusive, m), range(m, endExclusive));
18158
d5a620310f97 8015895: Int/LongStream.range/rangeClosed
psandoz
parents: 18154
diff changeset
   943
        } else {
d5a620310f97 8015895: Int/LongStream.range/rangeClosed
psandoz
parents: 18154
diff changeset
   944
            return StreamSupport.longStream(
18822
4b6be7c19547 8019395: Consolidate StreamSupport.{stream,parallelStream} into a single method
psandoz
parents: 18820
diff changeset
   945
                    new Streams.RangeLongSpliterator(startInclusive, endExclusive, false), false);
18158
d5a620310f97 8015895: Int/LongStream.range/rangeClosed
psandoz
parents: 18154
diff changeset
   946
        }
17195
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   947
    }
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   948
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   949
    /**
19850
93b368e54c1c 8011916: Spec update for java.util.stream
henryjen
parents: 19800
diff changeset
   950
     * Returns a sequential ordered {@code LongStream} from {@code startInclusive}
18158
d5a620310f97 8015895: Int/LongStream.range/rangeClosed
psandoz
parents: 18154
diff changeset
   951
     * (inclusive) to {@code endInclusive} (inclusive) by an incremental step of
d5a620310f97 8015895: Int/LongStream.range/rangeClosed
psandoz
parents: 18154
diff changeset
   952
     * {@code 1}.
17195
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   953
     *
18158
d5a620310f97 8015895: Int/LongStream.range/rangeClosed
psandoz
parents: 18154
diff changeset
   954
     * @apiNote
17195
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   955
     * <p>An equivalent sequence of increasing values can be produced
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   956
     * sequentially using a {@code for} loop as follows:
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   957
     * <pre>{@code
18158
d5a620310f97 8015895: Int/LongStream.range/rangeClosed
psandoz
parents: 18154
diff changeset
   958
     *     for (long i = startInclusive; i <= endInclusive ; i++) { ... }
17195
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   959
     * }</pre>
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   960
     *
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   961
     * @param startInclusive the (inclusive) initial value
18158
d5a620310f97 8015895: Int/LongStream.range/rangeClosed
psandoz
parents: 18154
diff changeset
   962
     * @param endInclusive the inclusive upper bound
17195
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   963
     * @return a sequential {@code LongStream} for the range of {@code long}
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   964
     *         elements
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   965
     */
18158
d5a620310f97 8015895: Int/LongStream.range/rangeClosed
psandoz
parents: 18154
diff changeset
   966
    public static LongStream rangeClosed(long startInclusive, final long endInclusive) {
d5a620310f97 8015895: Int/LongStream.range/rangeClosed
psandoz
parents: 18154
diff changeset
   967
        if (startInclusive > endInclusive) {
17195
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   968
            return empty();
18158
d5a620310f97 8015895: Int/LongStream.range/rangeClosed
psandoz
parents: 18154
diff changeset
   969
        } else if (endInclusive - startInclusive + 1 <= 0) {
d5a620310f97 8015895: Int/LongStream.range/rangeClosed
psandoz
parents: 18154
diff changeset
   970
            // Size of range > Long.MAX_VALUE
d5a620310f97 8015895: Int/LongStream.range/rangeClosed
psandoz
parents: 18154
diff changeset
   971
            // Split the range in two and concatenate
d5a620310f97 8015895: Int/LongStream.range/rangeClosed
psandoz
parents: 18154
diff changeset
   972
            // Note: if the range is [Long.MIN_VALUE, Long.MAX_VALUE] then
d5a620310f97 8015895: Int/LongStream.range/rangeClosed
psandoz
parents: 18154
diff changeset
   973
            // the lower range, [Long.MIN_VALUE, 0), and upper range,
d5a620310f97 8015895: Int/LongStream.range/rangeClosed
psandoz
parents: 18154
diff changeset
   974
            // [0, Long.MAX_VALUE], will both be further split in two
18820
a87cdd6a8834 8015315: Stream.concat methods
mduigou
parents: 18572
diff changeset
   975
            long m = startInclusive + Long.divideUnsigned(endInclusive - startInclusive, 2) + 1;
a87cdd6a8834 8015315: Stream.concat methods
mduigou
parents: 18572
diff changeset
   976
            return concat(range(startInclusive, m), rangeClosed(m, endInclusive));
17195
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   977
        } else {
18158
d5a620310f97 8015895: Int/LongStream.range/rangeClosed
psandoz
parents: 18154
diff changeset
   978
            return StreamSupport.longStream(
18822
4b6be7c19547 8019395: Consolidate StreamSupport.{stream,parallelStream} into a single method
psandoz
parents: 18820
diff changeset
   979
                    new Streams.RangeLongSpliterator(startInclusive, endInclusive, true), false);
17195
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   980
        }
e897ad52979e 8012650: Arrays streams methods
briangoetz
parents: 17167
diff changeset
   981
    }
18820
a87cdd6a8834 8015315: Stream.concat methods
mduigou
parents: 18572
diff changeset
   982
a87cdd6a8834 8015315: Stream.concat methods
mduigou
parents: 18572
diff changeset
   983
    /**
19850
93b368e54c1c 8011916: Spec update for java.util.stream
henryjen
parents: 19800
diff changeset
   984
     * Creates a lazily concatenated stream whose elements are all the
93b368e54c1c 8011916: Spec update for java.util.stream
henryjen
parents: 19800
diff changeset
   985
     * elements of the first stream followed by all the elements of the
21339
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   986
     * second stream.  The resulting stream is ordered if both
18820
a87cdd6a8834 8015315: Stream.concat methods
mduigou
parents: 18572
diff changeset
   987
     * of the input streams are ordered, and parallel if either of the input
19800
6e1fef53ea55 8017513: Support for closeable streams
henryjen
parents: 19214
diff changeset
   988
     * streams is parallel.  When the resulting stream is closed, the close
6e1fef53ea55 8017513: Support for closeable streams
henryjen
parents: 19214
diff changeset
   989
     * handlers for both input streams are invoked.
18820
a87cdd6a8834 8015315: Stream.concat methods
mduigou
parents: 18572
diff changeset
   990
     *
21339
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   991
     * @implNote
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   992
     * Use caution when constructing streams from repeated concatenation.
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   993
     * Accessing an element of a deeply concatenated stream can result in deep
29103
1dbde34ad64c 8073779: StackOverflowError called StackOverflowException in javadoc
igerasim
parents: 25859
diff changeset
   994
     * call chains, or even {@code StackOverflowError}.
21339
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20866
diff changeset
   995
     *
18820
a87cdd6a8834 8015315: Stream.concat methods
mduigou
parents: 18572
diff changeset
   996
     * @param a the first stream
19850
93b368e54c1c 8011916: Spec update for java.util.stream
henryjen
parents: 19800
diff changeset
   997
     * @param b the second stream
93b368e54c1c 8011916: Spec update for java.util.stream
henryjen
parents: 19800
diff changeset
   998
     * @return the concatenation of the two input streams
18820
a87cdd6a8834 8015315: Stream.concat methods
mduigou
parents: 18572
diff changeset
   999
     */
a87cdd6a8834 8015315: Stream.concat methods
mduigou
parents: 18572
diff changeset
  1000
    public static LongStream concat(LongStream a, LongStream b) {
a87cdd6a8834 8015315: Stream.concat methods
mduigou
parents: 18572
diff changeset
  1001
        Objects.requireNonNull(a);
a87cdd6a8834 8015315: Stream.concat methods
mduigou
parents: 18572
diff changeset
  1002
        Objects.requireNonNull(b);
a87cdd6a8834 8015315: Stream.concat methods
mduigou
parents: 18572
diff changeset
  1003
a87cdd6a8834 8015315: Stream.concat methods
mduigou
parents: 18572
diff changeset
  1004
        Spliterator.OfLong split = new Streams.ConcatSpliterator.OfLong(
a87cdd6a8834 8015315: Stream.concat methods
mduigou
parents: 18572
diff changeset
  1005
                a.spliterator(), b.spliterator());
19800
6e1fef53ea55 8017513: Support for closeable streams
henryjen
parents: 19214
diff changeset
  1006
        LongStream stream = StreamSupport.longStream(split, a.isParallel() || b.isParallel());
6e1fef53ea55 8017513: Support for closeable streams
henryjen
parents: 19214
diff changeset
  1007
        return stream.onClose(Streams.composedClose(a, b));
18820
a87cdd6a8834 8015315: Stream.concat methods
mduigou
parents: 18572
diff changeset
  1008
    }
18825
06636235cd12 8020062: Nest StreamBuilder interfaces inside relevant Stream interfaces
henryjen
parents: 18822
diff changeset
  1009
06636235cd12 8020062: Nest StreamBuilder interfaces inside relevant Stream interfaces
henryjen
parents: 18822
diff changeset
  1010
    /**
06636235cd12 8020062: Nest StreamBuilder interfaces inside relevant Stream interfaces
henryjen
parents: 18822
diff changeset
  1011
     * A mutable builder for a {@code LongStream}.
06636235cd12 8020062: Nest StreamBuilder interfaces inside relevant Stream interfaces
henryjen
parents: 18822
diff changeset
  1012
     *
19850
93b368e54c1c 8011916: Spec update for java.util.stream
henryjen
parents: 19800
diff changeset
  1013
     * <p>A stream builder has a lifecycle, which starts in a building
93b368e54c1c 8011916: Spec update for java.util.stream
henryjen
parents: 19800
diff changeset
  1014
     * phase, during which elements can be added, and then transitions to a built
93b368e54c1c 8011916: Spec update for java.util.stream
henryjen
parents: 19800
diff changeset
  1015
     * phase, after which elements may not be added.  The built phase begins
18825
06636235cd12 8020062: Nest StreamBuilder interfaces inside relevant Stream interfaces
henryjen
parents: 18822
diff changeset
  1016
     * begins when the {@link #build()} method is called, which creates an
06636235cd12 8020062: Nest StreamBuilder interfaces inside relevant Stream interfaces
henryjen
parents: 18822
diff changeset
  1017
     * ordered stream whose elements are the elements that were added to the
06636235cd12 8020062: Nest StreamBuilder interfaces inside relevant Stream interfaces
henryjen
parents: 18822
diff changeset
  1018
     * stream builder, in the order they were added.
06636235cd12 8020062: Nest StreamBuilder interfaces inside relevant Stream interfaces
henryjen
parents: 18822
diff changeset
  1019
     *
06636235cd12 8020062: Nest StreamBuilder interfaces inside relevant Stream interfaces
henryjen
parents: 18822
diff changeset
  1020
     * @see LongStream#builder()
06636235cd12 8020062: Nest StreamBuilder interfaces inside relevant Stream interfaces
henryjen
parents: 18822
diff changeset
  1021
     * @since 1.8
06636235cd12 8020062: Nest StreamBuilder interfaces inside relevant Stream interfaces
henryjen
parents: 18822
diff changeset
  1022
     */
06636235cd12 8020062: Nest StreamBuilder interfaces inside relevant Stream interfaces
henryjen
parents: 18822
diff changeset
  1023
    public interface Builder extends LongConsumer {
06636235cd12 8020062: Nest StreamBuilder interfaces inside relevant Stream interfaces
henryjen
parents: 18822
diff changeset
  1024
06636235cd12 8020062: Nest StreamBuilder interfaces inside relevant Stream interfaces
henryjen
parents: 18822
diff changeset
  1025
        /**
06636235cd12 8020062: Nest StreamBuilder interfaces inside relevant Stream interfaces
henryjen
parents: 18822
diff changeset
  1026
         * Adds an element to the stream being built.
06636235cd12 8020062: Nest StreamBuilder interfaces inside relevant Stream interfaces
henryjen
parents: 18822
diff changeset
  1027
         *
06636235cd12 8020062: Nest StreamBuilder interfaces inside relevant Stream interfaces
henryjen
parents: 18822
diff changeset
  1028
         * @throws IllegalStateException if the builder has already transitioned
06636235cd12 8020062: Nest StreamBuilder interfaces inside relevant Stream interfaces
henryjen
parents: 18822
diff changeset
  1029
         * to the built state
06636235cd12 8020062: Nest StreamBuilder interfaces inside relevant Stream interfaces
henryjen
parents: 18822
diff changeset
  1030
         */
06636235cd12 8020062: Nest StreamBuilder interfaces inside relevant Stream interfaces
henryjen
parents: 18822
diff changeset
  1031
        @Override
06636235cd12 8020062: Nest StreamBuilder interfaces inside relevant Stream interfaces
henryjen
parents: 18822
diff changeset
  1032
        void accept(long t);
06636235cd12 8020062: Nest StreamBuilder interfaces inside relevant Stream interfaces
henryjen
parents: 18822
diff changeset
  1033
06636235cd12 8020062: Nest StreamBuilder interfaces inside relevant Stream interfaces
henryjen
parents: 18822
diff changeset
  1034
        /**
06636235cd12 8020062: Nest StreamBuilder interfaces inside relevant Stream interfaces
henryjen
parents: 18822
diff changeset
  1035
         * Adds an element to the stream being built.
06636235cd12 8020062: Nest StreamBuilder interfaces inside relevant Stream interfaces
henryjen
parents: 18822
diff changeset
  1036
         *
06636235cd12 8020062: Nest StreamBuilder interfaces inside relevant Stream interfaces
henryjen
parents: 18822
diff changeset
  1037
         * @implSpec
06636235cd12 8020062: Nest StreamBuilder interfaces inside relevant Stream interfaces
henryjen
parents: 18822
diff changeset
  1038
         * The default implementation behaves as if:
06636235cd12 8020062: Nest StreamBuilder interfaces inside relevant Stream interfaces
henryjen
parents: 18822
diff changeset
  1039
         * <pre>{@code
06636235cd12 8020062: Nest StreamBuilder interfaces inside relevant Stream interfaces
henryjen
parents: 18822
diff changeset
  1040
         *     accept(t)
06636235cd12 8020062: Nest StreamBuilder interfaces inside relevant Stream interfaces
henryjen
parents: 18822
diff changeset
  1041
         *     return this;
06636235cd12 8020062: Nest StreamBuilder interfaces inside relevant Stream interfaces
henryjen
parents: 18822
diff changeset
  1042
         * }</pre>
06636235cd12 8020062: Nest StreamBuilder interfaces inside relevant Stream interfaces
henryjen
parents: 18822
diff changeset
  1043
         *
06636235cd12 8020062: Nest StreamBuilder interfaces inside relevant Stream interfaces
henryjen
parents: 18822
diff changeset
  1044
         * @param t the element to add
06636235cd12 8020062: Nest StreamBuilder interfaces inside relevant Stream interfaces
henryjen
parents: 18822
diff changeset
  1045
         * @return {@code this} builder
06636235cd12 8020062: Nest StreamBuilder interfaces inside relevant Stream interfaces
henryjen
parents: 18822
diff changeset
  1046
         * @throws IllegalStateException if the builder has already transitioned
06636235cd12 8020062: Nest StreamBuilder interfaces inside relevant Stream interfaces
henryjen
parents: 18822
diff changeset
  1047
         * to the built state
06636235cd12 8020062: Nest StreamBuilder interfaces inside relevant Stream interfaces
henryjen
parents: 18822
diff changeset
  1048
         */
06636235cd12 8020062: Nest StreamBuilder interfaces inside relevant Stream interfaces
henryjen
parents: 18822
diff changeset
  1049
        default Builder add(long t) {
06636235cd12 8020062: Nest StreamBuilder interfaces inside relevant Stream interfaces
henryjen
parents: 18822
diff changeset
  1050
            accept(t);
06636235cd12 8020062: Nest StreamBuilder interfaces inside relevant Stream interfaces
henryjen
parents: 18822
diff changeset
  1051
            return this;
06636235cd12 8020062: Nest StreamBuilder interfaces inside relevant Stream interfaces
henryjen
parents: 18822
diff changeset
  1052
        }
06636235cd12 8020062: Nest StreamBuilder interfaces inside relevant Stream interfaces
henryjen
parents: 18822
diff changeset
  1053
06636235cd12 8020062: Nest StreamBuilder interfaces inside relevant Stream interfaces
henryjen
parents: 18822
diff changeset
  1054
        /**
06636235cd12 8020062: Nest StreamBuilder interfaces inside relevant Stream interfaces
henryjen
parents: 18822
diff changeset
  1055
         * Builds the stream, transitioning this builder to the built state.
06636235cd12 8020062: Nest StreamBuilder interfaces inside relevant Stream interfaces
henryjen
parents: 18822
diff changeset
  1056
         * An {@code IllegalStateException} is thrown if there are further
06636235cd12 8020062: Nest StreamBuilder interfaces inside relevant Stream interfaces
henryjen
parents: 18822
diff changeset
  1057
         * attempts to operate on the builder after it has entered the built
06636235cd12 8020062: Nest StreamBuilder interfaces inside relevant Stream interfaces
henryjen
parents: 18822
diff changeset
  1058
         * state.
06636235cd12 8020062: Nest StreamBuilder interfaces inside relevant Stream interfaces
henryjen
parents: 18822
diff changeset
  1059
         *
06636235cd12 8020062: Nest StreamBuilder interfaces inside relevant Stream interfaces
henryjen
parents: 18822
diff changeset
  1060
         * @return the built stream
06636235cd12 8020062: Nest StreamBuilder interfaces inside relevant Stream interfaces
henryjen
parents: 18822
diff changeset
  1061
         * @throws IllegalStateException if the builder has already transitioned
06636235cd12 8020062: Nest StreamBuilder interfaces inside relevant Stream interfaces
henryjen
parents: 18822
diff changeset
  1062
         * to the built state
06636235cd12 8020062: Nest StreamBuilder interfaces inside relevant Stream interfaces
henryjen
parents: 18822
diff changeset
  1063
         */
06636235cd12 8020062: Nest StreamBuilder interfaces inside relevant Stream interfaces
henryjen
parents: 18822
diff changeset
  1064
        LongStream build();
06636235cd12 8020062: Nest StreamBuilder interfaces inside relevant Stream interfaces
henryjen
parents: 18822
diff changeset
  1065
    }
17167
87067e3340d3 8008682: Inital Streams public API
briangoetz
parents:
diff changeset
  1066
}