- code document all enumarable functions and iterators in containers

containers/enumerable.go

@@ -41,18 +41,18 @@ type EnumerableWithIndex interface {
 	// Returns a new container containing all elements for which the given function returns a true value.
 	Select(func(index int, value interface{}) bool) Container
 
-	// Passes each element of the collection to the given function and
+	// Passes each element of the container to the given function and
 	// returns true if the function ever returns true for any element.
 	Any(func(index int, value interface{}) bool) bool
 
-	// Passes each element of the collection to the given function and
+	// Passes each element of the container to the given function and
 	// returns true if the function returns true for all elements.
 	All(func(index int, value interface{}) bool) bool
 
-	// Passes each element of the collection to the given function and returns
-	// the first for which the function is true or -1,nil otherwise if no element
-	// matches the criteria.
-	Find(func(index int, value interface{}) bool) (index int, value interface{})
+	// Passes each element of the container to the given function and returns
+	// the first (index,value) for which the function is true or -1,nil otherwise
+	// if no element matches the criteria.
+	Find(func(index int, value interface{}) bool) (int, interface{})
 }
 
 // Enumerable function for ordered containers whose values whose elements are key value pairs.
@@ -60,23 +60,23 @@ type EnumerableWithKey interface {
 	// Calls the given function once for each element, passing that element's key and value.
 	Each(func(key interface{}, value interface{}))
 
-	// Invokes the given function once for each element and returns a
-	// container containing the values returned by the given function.
-	Map(func(key1 interface{}, value1 interface{}) (key2 interface{}, value2 interface{})) Container
+	// Invokes the given function once for each element and returns a container
+	// containing the values returned by the given function as key/value pairs.
+	Map(func(key interface{}, value interface{}) (interface{}, interface{})) Container
 
 	// Returns a new container containing all elements for which the given function returns a true value.
 	Select(func(key interface{}, value interface{}) bool) Container
 
-	// Passes each element of the collection to the given function and
+	// Passes each element of the container to the given function and
 	// returns true if the function ever returns true for any element.
 	Any(func(key interface{}, value interface{}) bool) bool
 
-	// Passes each element of the collection to the given function and
+	// Passes each element of the container to the given function and
 	// returns true if the function returns true for all elements.
 	All(func(key interface{}, value interface{}) bool) bool
 
-	// Passes each element of the collection to the given function and returns
-	// the first for which the function is true or nil,nil otherwise if no element
+	// Passes each element of the container to the given function and returns
+	// the first (key,value) for which the function is true or nil,nil otherwise if no element
 	// matches the criteria.
-	Find(func(key interface{}, value interface{}) bool) (key interface{}, value interface{})
+	Find(func(key interface{}, value interface{}) bool) (interface{}, interface{})
 }

containers/iterator.go

@@ -31,6 +31,7 @@ package containers
 // Stateful iterator for ordered containers whose values can be fetched by an index.
 type IteratorWithIndex interface {
 	// Moves the iterator to the next element and returns true if there was a next element in the container.
+	// If Next() returns true, then next element's index and value can be retrieved by Index() and Value().
 	// Modifies the state of the iterator.
 	Next() bool
 	// Returns the current element's value.
@@ -44,6 +45,7 @@ type IteratorWithIndex interface {
 // Stateful iterator for ordered containers whose elements are key value pairs.
 type IteratorWithKey interface {
 	// Moves the iterator to the next element and returns true if there was a next element in the container.
+	// If Next() returns true, then next element's key and value can be retrieved by Key() and Value().
 	// Modifies the state of the iterator.
 	Next() bool
 	// Returns the current element's value.

lists/arraylist/arraylist.go

@@ -183,23 +183,32 @@ type Iterator struct {
 	index int
 }
 
+// Returns a stateful iterator whose values can be fetched by an index.
 func (list *List) Iterator() Iterator {
 	return Iterator{list: list, index: -1}
 }
 
+// Moves the iterator to the next element and returns true if there was a next element in the container.
+// If Next() returns true, then next element's index and value can be retrieved by Index() and Value().
+// Modifies the state of the iterator.
 func (iterator *Iterator) Next() bool {
 	iterator.index += 1
 	return iterator.list.withinRange(iterator.index)
 }
 
+// Returns the current element's value.
+// Does not modify the state of the iterator.
 func (iterator *Iterator) Value() interface{} {
 	return iterator.list.elements[iterator.index]
 }
 
+// Returns the current element's index.
+// Does not modify the state of the iterator.
 func (iterator *Iterator) Index() int {
 	return iterator.index
 }
 
+// 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()
 	for iterator.Next() {
@@ -207,6 +216,8 @@ func (list *List) Each(f func(index int, value interface{})) {
 	}
 }
 
+// Invokes the given function once for each element and returns a
+// container containing the values returned by the given function.
 func (list *List) Map(f func(index int, value interface{}) interface{}) containers.Container {
 	newList := &List{}
 	iterator := list.Iterator()
@@ -216,6 +227,7 @@ func (list *List) Map(f func(index int, value interface{}) interface{}) containe
 	return newList
 }
 
+// Returns a new container containing all elements for which the given function returns a true value.
 func (list *List) Select(f func(index int, value interface{}) bool) containers.Container {
 	newList := &List{}
 	iterator := list.Iterator()
@@ -227,6 +239,8 @@ func (list *List) Select(f func(index int, value interface{}) bool) containers.C
 	return newList
 }
 
+// Passes each element of the collection to the given function and
+// returns true if the function ever returns true for any element.
 func (list *List) Any(f func(index int, value interface{}) bool) bool {
 	iterator := list.Iterator()
 	for iterator.Next() {
@@ -237,6 +251,8 @@ func (list *List) Any(f func(index int, value interface{}) bool) bool {
 	return false
 }
 
+// Passes each element of the collection to the given function and
+// returns true if the function returns true for all elements.
 func (list *List) All(f func(index int, value interface{}) bool) bool {
 	iterator := list.Iterator()
 	for iterator.Next() {
@@ -247,7 +263,10 @@ func (list *List) All(f func(index int, value interface{}) bool) bool {
 	return true
 }
 
-func (list *List) Find(f func(index int, value interface{}) bool) (index int, value interface{}) {
+// Passes each element of the container to the given function and returns
+// the first (index,value) for which the function is true or -1,nil otherwise
+// if no element matches the criteria.
+func (list *List) Find(f func(index int, value interface{}) bool) (int, interface{}) {
 	iterator := list.Iterator()
 	for iterator.Next() {
 		if f(iterator.Index(), iterator.Value()) {

lists/doublylinkedlist/doublylinkedlist.go

@@ -306,32 +306,41 @@ type Iterator struct {
 	element *element
 }
 
+// Returns a stateful iterator whose values can be fetched by an index.
 func (list *List) Iterator() Iterator {
 	return Iterator{list: list, index: -1, element: nil}
 }
 
+// Moves the iterator to the next element and returns true if there was a next element in the container.
+// If Next() returns true, then next element's index and value can be retrieved by Index() and Value().
+// Modifies the state of the iterator.
 func (iterator *Iterator) Next() bool {
 	iterator.index += 1
 	if !iterator.list.withinRange(iterator.index) {
 		iterator.element = nil
 		return false
 	}
-	if iterator.element == nil {
-		iterator.element = iterator.list.first
-	} else {
+	if iterator.element != nil {
 		iterator.element = iterator.element.next
+	} else {
+		iterator.element = iterator.list.first
 	}
 	return true
 }
 
+// Returns the current element's value.
+// Does not modify the state of the iterator.
 func (iterator *Iterator) Value() interface{} {
 	return iterator.element.value
 }
 
+// Returns the current element's index.
+// Does not modify the state of the iterator.
 func (iterator *Iterator) Index() int {
 	return iterator.index
 }
 
+// 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()
 	for iterator.Next() {
@@ -339,6 +348,8 @@ func (list *List) Each(f func(index int, value interface{})) {
 	}
 }
 
+// Invokes the given function once for each element and returns a
+// container containing the values returned by the given function.
 func (list *List) Map(f func(index int, value interface{}) interface{}) containers.Container {
 	newList := &List{}
 	iterator := list.Iterator()
@@ -348,6 +359,7 @@ func (list *List) Map(f func(index int, value interface{}) interface{}) containe
 	return newList
 }
 
+// Returns a new container containing all elements for which the given function returns a true value.
 func (list *List) Select(f func(index int, value interface{}) bool) containers.Container {
 	newList := &List{}
 	iterator := list.Iterator()
@@ -359,6 +371,8 @@ func (list *List) Select(f func(index int, value interface{}) bool) containers.C
 	return newList
 }
 
+// Passes each element of the container to the given function and
+// returns true if the function ever returns true for any element.
 func (list *List) Any(f func(index int, value interface{}) bool) bool {
 	iterator := list.Iterator()
 	for iterator.Next() {
@@ -369,6 +383,8 @@ func (list *List) Any(f func(index int, value interface{}) bool) bool {
 	return false
 }
 
+// Passes each element of the container to the given function and
+// returns true if the function returns true for all elements.
 func (list *List) All(f func(index int, value interface{}) bool) bool {
 	iterator := list.Iterator()
 	for iterator.Next() {
@@ -379,6 +395,9 @@ func (list *List) All(f func(index int, value interface{}) bool) bool {
 	return true
 }
 
+// Passes each element of the container to the given function and returns
+// the first (index,value) for which the function is true or -1,nil otherwise
+// if no element matches the criteria.
 func (list *List) Find(f func(index int, value interface{}) bool) (index int, value interface{}) {
 	iterator := list.Iterator()
 	for iterator.Next() {

lists/singlylinkedlist/singlylinkedlist.go

@@ -276,32 +276,41 @@ type Iterator struct {
 	element *element
 }
 
+// Returns a stateful iterator whose values can be fetched by an index.
 func (list *List) Iterator() Iterator {
 	return Iterator{list: list, index: -1, element: nil}
 }
 
+// Moves the iterator to the next element and returns true if there was a next element in the container.
+// If Next() returns true, then next element's index and value can be retrieved by Index() and Value().
+// Modifies the state of the iterator.
 func (iterator *Iterator) Next() bool {
 	iterator.index += 1
 	if !iterator.list.withinRange(iterator.index) {
 		iterator.element = nil
 		return false
 	}
-	if iterator.element == nil {
-		iterator.element = iterator.list.first
-	} else {
+	if iterator.element != nil {
 		iterator.element = iterator.element.next
+	} else {
+		iterator.element = iterator.list.first
 	}
 	return true
 }
 
+// Returns the current element's value.
+// Does not modify the state of the iterator.
 func (iterator *Iterator) Value() interface{} {
 	return iterator.element.value
 }
 
+// Returns the current element's index.
+// Does not modify the state of the iterator.
 func (iterator *Iterator) Index() int {
 	return iterator.index
 }
 
+// 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()
 	for iterator.Next() {
@@ -309,6 +318,8 @@ func (list *List) Each(f func(index int, value interface{})) {
 	}
 }
 
+// Invokes the given function once for each element and returns a
+// container containing the values returned by the given function.
 func (list *List) Map(f func(index int, value interface{}) interface{}) containers.Container {
 	newList := &List{}
 	iterator := list.Iterator()
@@ -318,6 +329,7 @@ func (list *List) Map(f func(index int, value interface{}) interface{}) containe
 	return newList
 }
 
+// Returns a new container containing all elements for which the given function returns a true value.
 func (list *List) Select(f func(index int, value interface{}) bool) containers.Container {
 	newList := &List{}
 	iterator := list.Iterator()
@@ -329,6 +341,8 @@ func (list *List) Select(f func(index int, value interface{}) bool) containers.C
 	return newList
 }
 
+// Passes each element of the container to the given function and
+// returns true if the function ever returns true for any element.
 func (list *List) Any(f func(index int, value interface{}) bool) bool {
 	iterator := list.Iterator()
 	for iterator.Next() {
@@ -339,6 +353,8 @@ func (list *List) Any(f func(index int, value interface{}) bool) bool {
 	return false
 }
 
+// Passes each element of the container to the given function and
+// returns true if the function returns true for all elements.
 func (list *List) All(f func(index int, value interface{}) bool) bool {
 	iterator := list.Iterator()
 	for iterator.Next() {
@@ -349,6 +365,9 @@ func (list *List) All(f func(index int, value interface{}) bool) bool {
 	return true
 }
 
+// Passes each element of the container to the given function and returns
+// the first (index,value) for which the function is true or -1,nil otherwise
+// if no element matches the criteria.
 func (list *List) Find(f func(index int, value interface{}) bool) (index int, value interface{}) {
 	iterator := list.Iterator()
 	for iterator.Next() {

maps/treemap/treemap.go

@@ -129,22 +129,31 @@ type Iterator struct {
 	iterator rbt.Iterator
 }
 
+// Returns a stateful iterator whose elements are key/value pairs.
 func (m *Map) Iterator() Iterator {
 	return Iterator{iterator: m.tree.Iterator()}
 }
 
+// Moves the iterator to the next element and returns true if there was a next element in the container.
+// If Next() returns true, then next element's key and value can be retrieved by Key() and Value().
+// Modifies the state of the iterator.
 func (iterator *Iterator) Next() bool {
 	return iterator.iterator.Next()
 }
 
+// Returns the current element's value.
+// Does not modify the state of the iterator.
 func (iterator *Iterator) Value() interface{} {
 	return iterator.iterator.Value()
 }
 
+// Returns the current element's key.
+// Does not modify the state of the iterator.
 func (iterator *Iterator) Key() interface{} {
 	return iterator.iterator.Key()
 }
 
+// Calls the given function once for each element, passing that element's key and value.
 func (m *Map) Each(f func(key interface{}, value interface{})) {
 	iterator := m.Iterator()
 	for iterator.Next() {
@@ -152,7 +161,9 @@ func (m *Map) Each(f func(key interface{}, value interface{})) {
 	}
 }
 
-func (m *Map) Map(f func(key1 interface{}, value1 interface{}) (key2 interface{}, value2 interface{})) containers.Container {
+// Invokes the given function once for each element and returns a container
+// containing the values returned by the given function as key/value pairs.
+func (m *Map) Map(f func(key1 interface{}, value1 interface{}) (interface{}, interface{})) containers.Container {
 	newMap := &Map{tree: rbt.NewWith(m.tree.Comparator)}
 	iterator := m.Iterator()
 	for iterator.Next() {
@@ -162,6 +173,7 @@ func (m *Map) Map(f func(key1 interface{}, value1 interface{}) (key2 interface{}
 	return newMap
 }
 
+// Returns a new container containing all elements for which the given function returns a true value.
 func (m *Map) Select(f func(key interface{}, value interface{}) bool) containers.Container {
 	newMap := &Map{tree: rbt.NewWith(m.tree.Comparator)}
 	iterator := m.Iterator()
@@ -173,6 +185,8 @@ func (m *Map) Select(f func(key interface{}, value interface{}) bool) containers
 	return newMap
 }
 
+// Passes each element of the container to the given function and
+// returns true if the function ever returns true for any element.
 func (m *Map) Any(f func(key interface{}, value interface{}) bool) bool {
 	iterator := m.Iterator()
 	for iterator.Next() {
@@ -183,6 +197,8 @@ func (m *Map) Any(f func(key interface{}, value interface{}) bool) bool {
 	return false
 }
 
+// Passes each element of the container to the given function and
+// returns true if the function returns true for all elements.
 func (m *Map) All(f func(key interface{}, value interface{}) bool) bool {
 	iterator := m.Iterator()
 	for iterator.Next() {
@@ -193,7 +209,10 @@ func (m *Map) All(f func(key interface{}, value interface{}) bool) bool {
 	return true
 }
 
-func (m *Map) Find(f func(key interface{}, value interface{}) bool) (key interface{}, value interface{}) {
+// Passes each element of the container to the given function and returns
+// the first (key,value) for which the function is true or nil,nil otherwise if no element
+// matches the criteria.
+func (m *Map) Find(f func(key interface{}, value interface{}) bool) (interface{}, interface{}) {
 	iterator := m.Iterator()
 	for iterator.Next() {
 		if f(iterator.Key(), iterator.Value()) {

sets/treeset/treeset.go

@@ -109,23 +109,32 @@ type Iterator struct {
 	iterator rbt.Iterator
 }
 
+// Returns a stateful iterator whose values can be fetched by an index.
 func (set *Set) Iterator() Iterator {
 	return Iterator{index: -1, iterator: set.tree.Iterator()}
 }
 
+// Moves the iterator to the next element and returns true if there was a next element in the container.
+// If Next() returns true, then next element's index and value can be retrieved by Index() and Value().
+// Modifies the state of the iterator.
 func (iterator *Iterator) Next() bool {
 	iterator.index += 1
 	return iterator.iterator.Next()
 }
 
+// Returns the current element's value.
+// Does not modify the state of the iterator.
 func (iterator *Iterator) Value() interface{} {
 	return iterator.iterator.Key()
 }
 
+// Returns the current element's index.
+// Does not modify the state of the iterator.
 func (iterator *Iterator) Index() int {
 	return iterator.index
 }
 
+// Calls the given function once for each element, passing that element's index and value.
 func (set *Set) Each(f func(index int, value interface{})) {
 	iterator := set.Iterator()
 	for iterator.Next() {
@@ -133,6 +142,8 @@ func (set *Set) Each(f func(index int, value interface{})) {
 	}
 }
 
+// Invokes the given function once for each element and returns a
+// container containing the values returned by the given function.
 func (set *Set) Map(f func(index int, value interface{}) interface{}) containers.Container {
 	newSet := &Set{tree: rbt.NewWith(set.tree.Comparator)}
 	iterator := set.Iterator()
@@ -142,6 +153,7 @@ func (set *Set) Map(f func(index int, value interface{}) interface{}) containers
 	return newSet
 }
 
+// Returns a new container containing all elements for which the given function returns a true value.
 func (set *Set) Select(f func(index int, value interface{}) bool) containers.Container {
 	newSet := &Set{tree: rbt.NewWith(set.tree.Comparator)}
 	iterator := set.Iterator()
@@ -153,6 +165,8 @@ func (set *Set) Select(f func(index int, value interface{}) bool) containers.Con
 	return newSet
 }
 
+// Passes each element of the container to the given function and
+// returns true if the function ever returns true for any element.
 func (set *Set) Any(f func(index int, value interface{}) bool) bool {
 	iterator := set.Iterator()
 	for iterator.Next() {
@@ -163,6 +177,8 @@ func (set *Set) Any(f func(index int, value interface{}) bool) bool {
 	return false
 }
 
+// Passes each element of the container to the given function and
+// returns true if the function returns true for all elements.
 func (set *Set) All(f func(index int, value interface{}) bool) bool {
 	iterator := set.Iterator()
 	for iterator.Next() {
@@ -173,7 +189,10 @@ func (set *Set) All(f func(index int, value interface{}) bool) bool {
 	return true
 }
 
-func (set *Set) Find(f func(index int, value interface{}) bool) (index int, value interface{}) {
+// Passes each element of the container to the given function and returns
+// the first (index,value) for which the function is true or -1,nil otherwise
+// if no element matches the criteria.
+func (set *Set) Find(f func(index int, value interface{}) bool) (int, interface{}) {
 	iterator := set.Iterator()
 	for iterator.Next() {
 		if f(iterator.Index(), iterator.Value()) {

stacks/arraystack/arraystack.go

@@ -101,20 +101,28 @@ type Iterator struct {
 	index int
 }
 
+// Returns a stateful iterator whose values can be fetched by an index.
 func (stack *Stack) Iterator() Iterator {
 	return Iterator{stack: stack, index: -1}
 }
 
+// Moves the iterator to the next element and returns true if there was a next element in the container.
+// If Next() returns true, then next element's index and value can be retrieved by Index() and Value().
+// Modifies the state of the iterator.
 func (iterator *Iterator) Next() bool {
 	iterator.index += 1
 	return iterator.stack.withinRange(iterator.index)
 }
 
+// Returns the current element's value.
+// Does not modify the state of the iterator.
 func (iterator *Iterator) Value() interface{} {
 	value, _ := iterator.stack.list.Get(iterator.stack.list.Size() - iterator.index - 1) // in reverse (LIFO)
 	return value
 }
 
+// Returns the current element's index.
+// Does not modify the state of the iterator.
 func (iterator *Iterator) Index() int {
 	return iterator.index
 }

stacks/linkedliststack/linkedliststack.go

@@ -97,20 +97,28 @@ type Iterator struct {
 	index int
 }
 
+// Returns a stateful iterator whose values can be fetched by an index.
 func (stack *Stack) Iterator() Iterator {
 	return Iterator{stack: stack, index: -1}
 }
 
+// Moves the iterator to the next element and returns true if there was a next element in the container.
+// If Next() returns true, then next element's index and value can be retrieved by Index() and Value().
+// Modifies the state of the iterator.
 func (iterator *Iterator) Next() bool {
 	iterator.index += 1
 	return iterator.stack.withinRange(iterator.index)
 }
 
+// Returns the current element's value.
+// Does not modify the state of the iterator.
 func (iterator *Iterator) Value() interface{} {
 	value, _ := iterator.stack.list.Get(iterator.index) // in reverse (LIFO)
 	return value
 }
 
+// Returns the current element's index.
+// Does not modify the state of the iterator.
 func (iterator *Iterator) Index() int {
 	return iterator.index
 }

trees/binaryheap/binaryheap.go

@@ -116,20 +116,28 @@ type Iterator struct {
 	index int
 }
 
+// Returns a stateful iterator whose values can be fetched by an index.
 func (heap *Heap) Iterator() Iterator {
 	return Iterator{heap: heap, index: -1}
 }
 
+// Moves the iterator to the next element and returns true if there was a next element in the container.
+// If Next() returns true, then next element's index and value can be retrieved by Index() and Value().
+// Modifies the state of the iterator.
 func (iterator *Iterator) Next() bool {
 	iterator.index += 1
 	return iterator.heap.withinRange(iterator.index)
 }
 
+// Returns the current element's value.
+// Does not modify the state of the iterator.
 func (iterator *Iterator) Value() interface{} {
 	value, _ := iterator.heap.list.Get(iterator.index)
 	return value
 }
 
+// Returns the current element's index.
+// Does not modify the state of the iterator.
 func (iterator *Iterator) Index() int {
 	return iterator.index
 }

trees/redblacktree/redblacktree.go

@@ -279,10 +279,14 @@ type Iterator struct {
 	left *Node
 }
 
+// Returns a stateful iterator whose elements are key/value pairs.
 func (tree *Tree) Iterator() Iterator {
 	return Iterator{tree: tree, left: nil}
 }
 
+// Moves the iterator to the next element and returns true if there was a next element in the container.
+// If Next() returns true, then next element's key and value can be retrieved by Key() and Value().
+// Modifies the state of the iterator.
 func (iterator *Iterator) Next() bool {
 	if iterator.left == nil {
 		iterator.left = iterator.tree.Left()
@@ -307,10 +311,14 @@ func (iterator *Iterator) Next() bool {
 	return false
 }
 
+// Returns the current element's value.
+// Does not modify the state of the iterator.
 func (iterator *Iterator) Value() interface{} {
 	return iterator.left.Value
 }
 
+// Returns the current element's key.
+// Does not modify the state of the iterator.
 func (iterator *Iterator) Key() interface{} {
 	return iterator.left.Key
 }