- iterator first on all structures with reversible iterators

containers/iterator.go

@@ -42,6 +42,10 @@ type IteratorWithIndex interface {
 	// Reset sets the iterator to the initial state.
 	// Call Next() to fetch the first element if any.
 	Reset()
+	// First moves the iterator to the first element and returns true if there was a first element in the container.
+	// If First() returns true, then first element's index and value can be retrieved by Index() and Value().
+	// Modifies the state of the iterator.
+	First() bool
 }
 
 // IteratorWithKey is a stateful iterator for ordered containers whose elements are key value pairs.
@@ -60,6 +64,10 @@ type IteratorWithKey interface {
 	// Reset sets the iterator to the initial state.
 	// Call Next() to fetch the first element if any.
 	Reset()
+	// First moves the iterator to the first element and returns true if there was a first element in the container.
+	// If First() returns true, then first element's key and value can be retrieved by Key() and Value().
+	// Modifies the state of the iterator.
+	First() bool
 }
 
 // ReverseIteratorWithIndex is stateful iterator for ordered containers whose values can be fetched by an index.
@@ -94,11 +102,11 @@ type ReverseIteratorWithIndex interface {
 // Last() function to move the iterator to the last element.
 type ReverseIteratorWithKey interface {
 	// Prev moves the iterator to the previous element and returns true if there was a previous element in the container.
-	// If Prev() returns true, then previous element's index and value can be retrieved by Key() and Value().
+	// If Prev() returns true, then previous element's key and value can be retrieved by Key() and Value().
 	// Modifies the state of the iterator.
 	Prev() bool
 	// Last moves the iterator to the last element and returns true if there was a last element in the container.
-	// If Last() returns true, then last element's index and value can be retrieved by Key() and Value().
+	// If Last() returns true, then last element's key and value can be retrieved by Key() and Value().
 	// Modifies the state of the iterator.
 	Last() bool
 

lists/arraylist/arraylist.go

@@ -230,6 +230,14 @@ func (iterator *Iterator) Reset() {
 	iterator.index = -1
 }
 
+// First moves the iterator to the first element and returns true if there was a first element in the container.
+// If First() returns true, then first element's index and value can be retrieved by Index() and Value().
+// Modifies the state of the iterator.
+func (iterator *Iterator) First() bool {
+	iterator.Reset()
+	return iterator.Next()
+}
+
 // Last moves the iterator to the last element and returns true if there was a last element in the container.
 // If Last() returns true, then last element's index and value can be retrieved by Index() and Value().
 // Modifies the state of the iterator.

lists/doublylinkedlist/doublylinkedlist.go

@@ -370,6 +370,14 @@ func (iterator *Iterator) Reset() {
 	iterator.element = nil
 }
 
+// First moves the iterator to the first element and returns true if there was a first element in the container.
+// If First() returns true, then first element's index and value can be retrieved by Index() and Value().
+// Modifies the state of the iterator.
+func (iterator *Iterator) First() bool {
+	iterator.Reset()
+	return iterator.Next()
+}
+
 // Last moves the iterator to the last element and returns true if there was a last element in the container.
 // If Last() returns true, then last element's index and value can be retrieved by Index() and Value().
 // Modifies the state of the iterator.

lists/singlylinkedlist/singlylinkedlist.go

@@ -323,6 +323,14 @@ func (iterator *Iterator) Reset() {
 	iterator.element = nil
 }
 
+// First moves the iterator to the first element and returns true if there was a first element in the container.
+// If First() returns true, then first element's index and value can be retrieved by Index() and Value().
+// Modifies the state of the iterator.
+func (iterator *Iterator) First() bool {
+	iterator.Reset()
+	return iterator.Next()
+}
+
 // Each calls the given function once for each element, passing that element's index and value.
 func (list *List) Each(f func(index int, value interface{})) {
 	iterator := list.Iterator()

maps/treemap/treemap.go

@@ -147,7 +147,7 @@ func (iterator *Iterator) Next() bool {
 }
 
 // Prev moves the iterator to the previous element and returns true if there was a previous element in the container.
-// If Prev() returns true, then previous element's index and value can be retrieved by Key() and Value().
+// If Prev() returns true, then previous element's key and value can be retrieved by Key() and Value().
 // Modifies the state of the iterator.
 func (iterator *Iterator) Prev() bool {
 	return iterator.iterator.Prev()
@@ -171,8 +171,16 @@ func (iterator *Iterator) Reset() {
 	iterator.iterator.Reset()
 }
 
+// First moves the iterator to the first element and returns true if there was a first element in the container.
+// If First() returns true, then first element's key and value can be retrieved by Key() and Value().
+// Modifies the state of the iterator
+func (iterator *Iterator) First() bool {
+	iterator.Reset()
+	return iterator.Next()
+}
+
 // Last moves the iterator to the last element and returns true if there was a last element in the container.
-// If Last() returns true, then last element's index and value can be retrieved by Key() and Value().
+// If Last() returns true, then last element's key and value can be retrieved by Key() and Value().
 // Modifies the state of the iterator.
 func (iterator *Iterator) Last() bool {
 	return iterator.iterator.Last()

sets/treeset/treeset.go

@@ -158,6 +158,14 @@ func (iterator *Iterator) Reset() {
 	iterator.iterator.Reset()
 }
 
+// First moves the iterator to the first element and returns true if there was a first element in the container.
+// If First() returns true, then first element's index and value can be retrieved by Index() and Value().
+// Modifies the state of the iterator.
+func (iterator *Iterator) First() bool {
+	iterator.Reset()
+	return iterator.Next()
+}
+
 // Last moves the iterator to the last element and returns true if there was a last element in the container.
 // If Last() returns true, then last element's index and value can be retrieved by Index() and Value().
 // Modifies the state of the iterator.

stacks/arraystack/arraystack.go

@@ -149,6 +149,14 @@ func (iterator *Iterator) Reset() {
 	iterator.index = -1
 }
 
+// First moves the iterator to the first element and returns true if there was a first element in the container.
+// If First() returns true, then first element's index and value can be retrieved by Index() and Value().
+// Modifies the state of the iterator.
+func (iterator *Iterator) First() bool {
+	iterator.Reset()
+	return iterator.Next()
+}
+
 // Last moves the iterator to the last element and returns true if there was a last element in the container.
 // If Last() returns true, then last element's index and value can be retrieved by Index() and Value().
 // Modifies the state of the iterator.

stacks/linkedliststack/linkedliststack.go

@@ -134,6 +134,14 @@ func (iterator *Iterator) Reset() {
 	iterator.index = -1
 }
 
+// First moves the iterator to the first element and returns true if there was a first element in the container.
+// If First() returns true, then first element's index and value can be retrieved by Index() and Value().
+// Modifies the state of the iterator.
+func (iterator *Iterator) First() bool {
+	iterator.Reset()
+	return iterator.Next()
+}
+
 // String returns a string representation of container
 func (stack *Stack) String() string {
 	str := "LinkedListStack\n"

trees/binaryheap/binaryheap.go

@@ -165,6 +165,14 @@ func (iterator *Iterator) Reset() {
 	iterator.index = -1
 }
 
+// First moves the iterator to the first element and returns true if there was a first element in the container.
+// If First() returns true, then first element's index and value can be retrieved by Index() and Value().
+// Modifies the state of the iterator.
+func (iterator *Iterator) First() bool {
+	iterator.Reset()
+	return iterator.Next()
+}
+
 // Last moves the iterator to the last element and returns true if there was a last element in the container.
 // If Last() returns true, then last element's index and value can be retrieved by Index() and Value().
 // Modifies the state of the iterator.

trees/redblacktree/redblacktree.go

@@ -319,7 +319,7 @@ func (iterator *Iterator) Next() bool {
 }
 
 // Prev moves the iterator to the previous element and returns true if there was a previous element in the container.
-// If Prev() returns true, then previous element's index and value can be retrieved by Key() and Value().
+// If Prev() returns true, then previous element's key and value can be retrieved by Key() and Value().
 // Modifies the state of the iterator.
 func (iterator *Iterator) Prev() bool {
 	if iterator.node == nil {
@@ -363,8 +363,16 @@ func (iterator *Iterator) Reset() {
 	iterator.node = nil
 }
 
+// First moves the iterator to the first element and returns true if there was a first element in the container.
+// If First() returns true, then first element's key and value can be retrieved by Key() and Value().
+// Modifies the state of the iterator
+func (iterator *Iterator) First() bool {
+	iterator.Reset()
+	return iterator.Next()
+}
+
 // Last moves the iterator to the last element and returns true if there was a last element in the container.
-// If Last() returns true, then last element's index and value can be retrieved by Key() and Value().
+// If Last() returns true, then last element's key and value can be retrieved by Key() and Value().
 // Modifies the state of the iterator.
 func (iterator *Iterator) Last() bool {
 	iterator.node = iterator.tree.Right()