github.com/searKing/golang/go@v1.2.74/container/stream/base_stream.go (about)

     1  // Copyright 2020 The searKing Author. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  package stream
     6  
     7  import (
     8  	"io"
     9  
    10  	"github.com/searKing/golang/go/util"
    11  	"github.com/searKing/golang/go/util/spliterator"
    12  )
    13  
    14  /**
    15   * Base interface for streams, which are sequences of elements supporting
    16   * sequential and parallel aggregate operations.  The following example
    17   * illustrates an aggregate operation using the stream types {@link Stream}
    18   * and {@link IntStream}, computing the sum of the weights of the red widgets:
    19   *
    20   * <pre>{@code
    21   *     int sum = widgets.stream()
    22   *                      .filter(w -> w.getColor() == RED)
    23   *                      .mapToInt(w -> w.getWeight())
    24   *                      .sum();
    25   * }</pre>
    26   *
    27   * See the class documentation for {@link Stream} and the package documentation
    28   * for <a href="package-summary.html">java.util.stream</a> for additional
    29   * specification of streams, stream operations, stream pipelines, and
    30   * parallelism, which governs the behavior of all stream types.
    31   *
    32   * @param <T> the type of the stream elements
    33   * @param <S> the type of the stream implementing {@code BaseStream}
    34   * @since 1.8
    35   * @see Stream
    36   * @see IntStream
    37   * @see LongStream
    38   * @see DoubleStream
    39   * @see <a href="package-summary.html">java.util.stream</a>
    40   */
    41  type BaseStream interface {
    42  	io.Closer
    43  
    44  	/**
    45  	 * Returns an iterator for the elements of this stream.
    46  	 *
    47  	 * <p>This is a <a href="package-summary.html#StreamOps">terminal
    48  	 * operation</a>.
    49  	 *
    50  	 * @return the element iterator for this stream
    51  	 */
    52  	Iterator() util.Iterator
    53  
    54  	/**
    55  	 * Returns a spliterator for the elements of this stream.
    56  	 *
    57  	 * <p>This is a <a href="package-summary.html#StreamOps">terminal
    58  	 * operation</a>.
    59  	 *
    60  	 * <p>
    61  	 * The returned spliterator should report the set of characteristics derived
    62  	 * from the stream pipeline (namely the characteristics derived from the
    63  	 * stream source spliterator and the intermediate operations).
    64  	 * Implementations may report a sub-set of those characteristics.  For
    65  	 * example, it may be too expensive to compute the entire set for some or
    66  	 * all possible stream pipelines.
    67  	 *
    68  	 * @return the element spliterator for this stream
    69  	 */
    70  	Spliterator() spliterator.Spliterator
    71  
    72  	/**
    73  	 * Returns whether this stream, if a terminal operation were to be executed,
    74  	 * would execute in parallel.  Calling this method after invoking an
    75  	 * terminal stream operation method may yield unpredictable results.
    76  	 *
    77  	 * @return {@code true} if this stream would execute in parallel if executed
    78  	 */
    79  	IsParallel() bool
    80  
    81  	/**
    82  	 * Returns an equivalent stream that is sequential.  May return
    83  	 * itself, either because the stream was already sequential, or because
    84  	 * the underlying stream state was modified to be sequential.
    85  	 *
    86  	 * <p>This is an <a href="package-summary.html#StreamOps">intermediate
    87  	 * operation</a>.
    88  	 *
    89  	 * @return a sequential stream
    90  	 */
    91  	Sequential() BaseStream
    92  
    93  	/**
    94  	 * Returns an equivalent stream that is parallel.  May return
    95  	 * itself, either because the stream was already parallel, or because
    96  	 * the underlying stream state was modified to be parallel.
    97  	 *
    98  	 * <p>This is an <a href="package-summary.html#StreamOps">intermediate
    99  	 * operation</a>.
   100  	 *
   101  	 * @return a parallel stream
   102  	 */
   103  	Parallel() BaseStream
   104  
   105  	/**
   106  	 * Returns an equivalent stream that is
   107  	 * <a href="package-summary.html#Ordering">unordered</a>.  May return
   108  	 * itself, either because the stream was already unordered, or because
   109  	 * the underlying stream state was modified to be unordered.
   110  	 *
   111  	 * <p>This is an <a href="package-summary.html#StreamOps">intermediate
   112  	 * operation</a>.
   113  	 *
   114  	 * @return an unordered stream
   115  	 */
   116  	Unordered() BaseStream
   117  
   118  	/**
   119  	 * Returns an equivalent stream with an additional close handler.  Close
   120  	 * handlers are run when the {@link #close()} method
   121  	 * is called on the stream, and are executed in the order they were
   122  	 * added.  All close handlers are run, even if earlier close handlers throw
   123  	 * exceptions.  If any close handler throws an exception, the first
   124  	 * exception thrown will be relayed to the caller of {@code close()}, with
   125  	 * any remaining exceptions added to that exception as suppressed exceptions
   126  	 * (unless one of the remaining exceptions is the same exception as the
   127  	 * first exception, since an exception cannot suppress itself.)  May
   128  	 * return itself.
   129  	 *
   130  	 * <p>This is an <a href="package-summary.html#StreamOps">intermediate
   131  	 * operation</a>.
   132  	 *
   133  	 * @param closeHandler A task to execute when the stream is closed
   134  	 * @return a stream with a handler that is run if the stream is closed
   135  	 */
   136  	OnClose(closeHandler util.Runnable) BaseStream
   137  }