github.com/songzhibin97/go-baseutils@v0.0.2-0.20240302024150-487d8ce9c082/structure/containers/iterator.go (about)

     1  package containers
     2  
     3  // IteratorWithIndex is stateful iterator for ordered containers whose values can be fetched by an index.
     4  type IteratorWithIndex[V any] interface {
     5  	// Next moves the iterator to the next element and returns true if there was a next element in the container.
     6  	// If Next() returns true, then next element's index and value can be retrieved by Index() and Value().
     7  	// If Next() was called for the first time, then it will point the iterator to the first element if it exists.
     8  	// Modifies the state of the iterator.
     9  	Next() bool
    10  
    11  	// Value returns the current element's value.
    12  	// Does not modify the state of the iterator.
    13  	Value() V
    14  
    15  	// Index returns the current element's index.
    16  	// Does not modify the state of the iterator.
    17  	Index() int
    18  
    19  	// Begin resets the iterator to its initial state (one-before-first)
    20  	// Call Next() to fetch the first element if any.
    21  	Begin()
    22  
    23  	// First moves the iterator to the first element and returns true if there was a first element in the container.
    24  	// If First() returns true, then first element's index and value can be retrieved by Index() and Value().
    25  	// Modifies the state of the iterator.
    26  	First() bool
    27  
    28  	// NextTo moves the iterator to the next element from current position that satisfies the condition given by the
    29  	// passed function, and returns true if there was a next element in the container.
    30  	// If NextTo() returns true, then next element's index and value can be retrieved by Index() and Value().
    31  	// Modifies the state of the iterator.
    32  	NextTo(func(index int, value V) bool) bool
    33  }
    34  
    35  // IteratorWithKey is a stateful iterator for ordered containers whose elements are key value pairs.
    36  type IteratorWithKey[K, V any] interface {
    37  	// Next moves the iterator to the next element and returns true if there was a next element in the container.
    38  	// If Next() returns true, then next element's key and value can be retrieved by Key() and Value().
    39  	// If Next() was called for the first time, then it will point the iterator to the first element if it exists.
    40  	// Modifies the state of the iterator.
    41  	Next() bool
    42  
    43  	// Value returns the current element's value.
    44  	// Does not modify the state of the iterator.
    45  	Value() V
    46  
    47  	// Key returns the current element's key.
    48  	// Does not modify the state of the iterator.
    49  	Key() K
    50  
    51  	// Begin resets the iterator to its initial state (one-before-first)
    52  	// Call Next() to fetch the first element if any.
    53  	Begin()
    54  
    55  	// First moves the iterator to the first element and returns true if there was a first element in the container.
    56  	// If First() returns true, then first element's key and value can be retrieved by Key() and Value().
    57  	// Modifies the state of the iterator.
    58  	First() bool
    59  
    60  	// NextTo moves the iterator to the next element from current position that satisfies the condition given by the
    61  	// passed function, and returns true if there was a next element in the container.
    62  	// If NextTo() returns true, then next element's key and value can be retrieved by Key() and Value().
    63  	// Modifies the state of the iterator.
    64  	NextTo(func(key K, value V) bool) bool
    65  }
    66  
    67  // ReverseIteratorWithIndex is stateful iterator for ordered containers whose values can be fetched by an index.
    68  //
    69  // Essentially it is the same as IteratorWithIndex, but provides additional:
    70  //
    71  // # Prev() function to enable traversal in reverse
    72  //
    73  // Last() function to move the iterator to the last element.
    74  //
    75  // End() function to move the iterator past the last element (one-past-the-end).
    76  type ReverseIteratorWithIndex[V any] interface {
    77  	// Prev moves the iterator to the previous element and returns true if there was a previous element in the container.
    78  	// If Prev() returns true, then previous element's index and value can be retrieved by Index() and Value().
    79  	// Modifies the state of the iterator.
    80  	Prev() bool
    81  
    82  	// End moves the iterator past the last element (one-past-the-end).
    83  	// Call Prev() to fetch the last element if any.
    84  	End()
    85  
    86  	// Last moves the iterator to the last element and returns true if there was a last element in the container.
    87  	// If Last() returns true, then last element's index and value can be retrieved by Index() and Value().
    88  	// Modifies the state of the iterator.
    89  	Last() bool
    90  
    91  	// PrevTo moves the iterator to the previous element from current position that satisfies the condition given by the
    92  	// passed function, and returns true if there was a next element in the container.
    93  	// If PrevTo() returns true, then next element's index and value can be retrieved by Index() and Value().
    94  	// Modifies the state of the iterator.
    95  	PrevTo(func(index int, value V) bool) bool
    96  
    97  	IteratorWithIndex[V]
    98  }
    99  
   100  // ReverseIteratorWithKey is a stateful iterator for ordered containers whose elements are key value pairs.
   101  //
   102  // Essentially it is the same as IteratorWithKey, but provides additional:
   103  //
   104  // # Prev() function to enable traversal in reverse
   105  //
   106  // Last() function to move the iterator to the last element.
   107  type ReverseIteratorWithKey[K, V any] interface {
   108  	// Prev moves the iterator to the previous element and returns true if there was a previous element in the container.
   109  	// If Prev() returns true, then previous element's key and value can be retrieved by Key() and Value().
   110  	// Modifies the state of the iterator.
   111  	Prev() bool
   112  
   113  	// End moves the iterator past the last element (one-past-the-end).
   114  	// Call Prev() to fetch the last element if any.
   115  	End()
   116  
   117  	// Last moves the iterator to the last element and returns true if there was a last element in the container.
   118  	// If Last() returns true, then last element's key and value can be retrieved by Key() and Value().
   119  	// Modifies the state of the iterator.
   120  	Last() bool
   121  
   122  	// PrevTo moves the iterator to the previous element from current position that satisfies the condition given by the
   123  	// passed function, and returns true if there was a next element in the container.
   124  	// If PrevTo() returns true, then next element's key and value can be retrieved by Key() and Value().
   125  	// Modifies the state of the iterator.
   126  	PrevTo(func(key K, value V) bool) bool
   127  
   128  	IteratorWithKey[K, V]
   129  }