github.com/searKing/golang/go@v1.2.74/container/stream/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  	"context"
     9  
    10  	"github.com/searKing/golang/go/util"
    11  	"github.com/searKing/golang/go/util/function/binary"
    12  	"github.com/searKing/golang/go/util/function/consumer"
    13  	"github.com/searKing/golang/go/util/function/predicate"
    14  	"github.com/searKing/golang/go/util/optional"
    15  )
    16  
    17  /**
    18   * A sequence of elements supporting sequential and parallel aggregate
    19   * operations.  The following example illustrates an aggregate operation using
    20   * {@link Stream} and {@link IntStream}:
    21   *
    22   * <pre>{@code
    23   *     int sum = widgets.stream()
    24   *                      .filter(w -> w.getColor() == RED)
    25   *                      .mapToInt(w -> w.getWeight())
    26   *                      .sum();
    27   * }</pre>
    28   *
    29   * In this example, {@code widgets} is a {@code Collection<Widget>}.  We create
    30   * a stream of {@code Widget} objects via {@link Collection#stream Collection.stream()},
    31   * filter it to produce a stream containing only the red widgets, and then
    32   * transform it into a stream of {@code int} values representing the weight of
    33   * each red widget. Then this stream is summed to produce a total weight.
    34   *
    35   * <p>In addition to {@code Stream}, which is a stream of object references,
    36   * there are primitive specializations for {@link IntStream}, {@link LongStream},
    37   * and {@link DoubleStream}, all of which are referred to as "streams" and
    38   * conform to the characteristics and restrictions described here.
    39   *
    40   * <p>To perform a computation, stream
    41   * <a href="package-summary.html#StreamOps">operations</a> are composed into a
    42   * <em>stream pipeline</em>.  A stream pipeline consists of a source (which
    43   * might be an array, a collection, a generator function, an I/O channel,
    44   * etc), zero or more <em>intermediate operations</em> (which transform a
    45   * stream into another stream, such as {@link Stream#filter(Predicate)}), and a
    46   * <em>terminal operation</em> (which produces a result or side-effect, such
    47   * as {@link Stream#count()} or {@link Stream#forEach(Consumer)}).
    48   * Streams are lazy; computation on the source data is only performed when the
    49   * terminal operation is initiated, and source elements are consumed only
    50   * as needed.
    51   *
    52   * <p>A stream implementation is permitted significant latitude in optimizing
    53   * the computation of the result.  For example, a stream implementation is free
    54   * to elide operations (or entire stages) from a stream pipeline -- and
    55   * therefore elide invocation of behavioral parameters -- if it can prove that
    56   * it would not affect the result of the computation.  This means that
    57   * side-effects of behavioral parameters may not always be executed and should
    58   * not be relied upon, unless otherwise specified (such as by the terminal
    59   * operations {@code forEach} and {@code forEachOrdered}). (For a specific
    60   * example of such an optimization, see the API note documented on the
    61   * {@link #count} operation.  For more detail, see the
    62   * <a href="package-summary.html#SideEffects">side-effects</a> section of the
    63   * stream package documentation.)
    64   *
    65   * <p>Collections and streams, while bearing some superficial similarities,
    66   * have different goals.  Collections are primarily concerned with the efficient
    67   * management of, and access to, their elements.  By contrast, streams do not
    68   * provide a means to directly access or manipulate their elements, and are
    69   * instead concerned with declaratively describing their source and the
    70   * computational operations which will be performed in aggregate on that source.
    71   * However, if the provided stream operations do not offer the desired
    72   * functionality, the {@link #iterator()} and {@link #spliterator()} operations
    73   * can be used to perform a controlled traversal.
    74   *
    75   * <p>A stream pipeline, like the "widgets" example above, can be viewed as
    76   * a <em>query</em> on the stream source.  Unless the source was explicitly
    77   * designed for concurrent modification (such as a {@link ConcurrentHashMap}),
    78   * unpredictable or erroneous behavior may result from modifying the stream
    79   * source while it is being queried.
    80   *
    81   * <p>Most stream operations accept parameters that describe user-specified
    82   * behavior, such as the lambda expression {@code w -> w.getWeight()} passed to
    83   * {@code mapToInt} in the example above.  To preserve correct behavior,
    84   * these <em>behavioral parameters</em>:
    85   * <ul>
    86   * <li>must be <a href="package-summary.html#NonInterference">non-interfering</a>
    87   * (they do not modify the stream source); and</li>
    88   * <li>in most cases must be <a href="package-summary.html#Statelessness">stateless</a>
    89   * (their result should not depend on any state that might change during execution
    90   * of the stream pipeline).</li>
    91   * </ul>
    92   *
    93   * <p>Such parameters are always instances of a
    94   * <a href="../function/package-summary.html">functional interface</a> such
    95   * as {@link java.util.function.Function}, and are often lambda expressions or
    96   * method references.  Unless otherwise specified these parameters must be
    97   * <em>non-null</em>.
    98   *
    99   * <p>A stream should be operated on (invoking an intermediate or terminal stream
   100   * operation) only once.  This rules out, for example, "forked" streams, where
   101   * the same source feeds two or more pipelines, or multiple traversals of the
   102   * same stream.  A stream implementation may throw {@link IllegalStateException}
   103   * if it detects that the stream is being reused. However, since some stream
   104   * operations may return their receiver rather than a new stream object, it may
   105   * not be possible to detect reuse in all cases.
   106   *
   107   * <p>Streams have a {@link #close()} method and implement {@link AutoCloseable}.
   108   * Operating on a stream after it has been closed will throw {@link IllegalStateException}.
   109   * Most stream instances do not actually need to be closed after use, as they
   110   * are backed by collections, arrays, or generating functions, which require no
   111   * special resource management. Generally, only streams whose source is an IO channel,
   112   * such as those returned by {@link Files#lines(Path)}, will require closing. If a
   113   * stream does require closing, it must be opened as a resource within a try-with-resources
   114   * statement or similar control structure to ensure that it is closed promptly after its
   115   * operations have completed.
   116   *
   117   * <p>Stream pipelines may execute either sequentially or in
   118   * <a href="package-summary.html#Parallelism">parallel</a>.  This
   119   * execution mode is a property of the stream.  Streams are created
   120   * with an initial choice of sequential or parallel execution.  (For example,
   121   * {@link Collection#stream() Collection.stream()} creates a sequential stream,
   122   * and {@link Collection#parallelStream() Collection.parallelStream()} creates
   123   * a parallel one.)  This choice of execution mode may be modified by the
   124   * {@link #sequential()} or {@link #parallel()} methods, and may be queried with
   125   * the {@link #isParallel()} method.
   126   *
   127   * @param <T> the type of the stream elements
   128   * @since 1.8
   129   * @see IntStream
   130   * @see LongStream
   131   * @see DoubleStream
   132   * @see <a href="package-summary.html">java.util.stream</a>
   133   */
   134  type Stream interface {
   135  	BaseStream
   136  	Filter(ctx context.Context, predicate predicate.Predicater) Stream
   137  	Map(ctx context.Context, f func(interface{}) interface{}) Stream
   138  	Distinct(ctx context.Context, comparator util.Comparator) Stream
   139  	Sorted(lesser func(interface{}, interface{}) int) Stream
   140  	Peek(ctx context.Context, action consumer.Consumer) Stream
   141  	Limit(maxSize int) Stream
   142  	Skip(n int) Stream
   143  	TakeWhile(ctx context.Context, predicate predicate.Predicater) Stream
   144  	TakeUntil(ctx context.Context, predicate predicate.Predicater) Stream
   145  	DropWhile(ctx context.Context, predicate predicate.Predicater) Stream
   146  	DropUntil(ctx context.Context, predicate predicate.Predicater) Stream
   147  	ForEach(ctx context.Context, action consumer.Consumer)
   148  	ForEachOrdered(ctx context.Context, action consumer.Consumer)
   149  	ToSlice() interface{}
   150  	Reduce(ctx context.Context, accumulator binary.BiFunction, identity ...interface{}) optional.Optional
   151  	Min(ctx context.Context, comparator util.Comparator) optional.Optional
   152  	Max(ctx context.Context, comparator util.Comparator) optional.Optional
   153  	Count() int
   154  	AnyMatch(ctx context.Context, predicate predicate.Predicater) bool
   155  	AllMatch(ctx context.Context, predicate predicate.Predicater) bool
   156  	NoneMatch(ctx context.Context, predicate predicate.Predicater) bool
   157  	FindFirst(ctx context.Context, predicate predicate.Predicater) optional.Optional
   158  	FindFirstIndex(ctx context.Context, predicate predicate.Predicater) int
   159  	FindAny(ctx context.Context, predicate predicate.Predicater) optional.Optional
   160  	FindAnyIndex(ctx context.Context, predicate predicate.Predicater) int
   161  	Empty() interface{}
   162  	Of() Stream
   163  	Concat(s2 Stream) Stream
   164  	ConcatWithValue(v interface{}) Stream
   165  
   166  	//grammar surger for count
   167  	Size() int
   168  	Length() int
   169  }