github.com/shogo82148/std@v1.22.1-0.20240327122250-4e474527810c/iter/iter.go (about)

     1  // Copyright 2023 The Go Authors. 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  //go:build goexperiment.rangefunc
     6  
     7  // Package iter provides basic definitions and operations
     8  // related to iteration in Go.
     9  //
    10  // This package is experimental and can only be imported
    11  // when building with GOEXPERIMENT=rangefunc.
    12  package iter
    13  
    14  // Seq is an iterator over sequences of individual values.
    15  // When called as seq(yield), seq calls yield(v) for each value v in the sequence,
    16  // stopping early if yield returns false.
    17  type Seq[V any] func(yield func(V) bool)
    18  
    19  // Seq2 is an iterator over sequences of pairs of values, most commonly key-value pairs.
    20  // When called as seq(yield), seq calls yield(k, v) for each pair (k, v) in the sequence,
    21  // stopping early if yield returns false.
    22  type Seq2[K, V any] func(yield func(K, V) bool)
    23  
    24  // Pull converts the “push-style” iterator sequence seq
    25  // into a “pull-style” iterator accessed by the two functions
    26  // next and stop.
    27  //
    28  // Next returns the next value in the sequence
    29  // and a boolean indicating whether the value is valid.
    30  // When the sequence is over, next returns the zero V and false.
    31  // It is valid to call next after reaching the end of the sequence
    32  // or after calling stop. These calls will continue
    33  // to return the zero V and false.
    34  //
    35  // Stop ends the iteration. It must be called when the caller is
    36  // no longer interested in next values and next has not yet
    37  // signaled that the sequence is over (with a false boolean return).
    38  // It is valid to call stop multiple times and when next has
    39  // already returned false.
    40  //
    41  // It is an error to call next or stop from multiple goroutines
    42  // simultaneously.
    43  func Pull[V any](seq Seq[V]) (next func() (V, bool), stop func())
    44  
    45  // Pull2 converts the “push-style” iterator sequence seq
    46  // into a “pull-style” iterator accessed by the two functions
    47  // next and stop.
    48  //
    49  // Next returns the next pair in the sequence
    50  // and a boolean indicating whether the pair is valid.
    51  // When the sequence is over, next returns a pair of zero values and false.
    52  // It is valid to call next after reaching the end of the sequence
    53  // or after calling stop. These calls will continue
    54  // to return a pair of zero values and false.
    55  //
    56  // Stop ends the iteration. It must be called when the caller is
    57  // no longer interested in next values and next has not yet
    58  // signaled that the sequence is over (with a false boolean return).
    59  // It is valid to call stop multiple times and when next has
    60  // already returned false.
    61  //
    62  // It is an error to call next or stop from multiple goroutines
    63  // simultaneously.
    64  func Pull2[K, V any](seq Seq2[K, V]) (next func() (K, V, bool), stop func())