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