Iterators

heap/MaxBinaryHeap/maxBinaryHeap.go

@@ -1,6 +1,8 @@
 package maxbinaryheap
 
 import (
+	"iter"
+
 	comparator "github.com/hmcalister/Go-DSA/utils/Comparator"
 	dsa_error "github.com/hmcalister/Go-DSA/utils/DSA_Error"
 )
@@ -249,3 +251,22 @@ func Fold[T any, G any](heap *MaxBinaryHeap[T], initialAccumulator G, f func(ite
 
 	return accumulator
 }
+
+// Iterate over the items of the heap.
+// In case it matters, the iteration is effectively in "reading order" along the heap.
+// This is *not* a sorted order. To iterate in sorted order you may either extract the heap items with Items() and sort,
+// or continually pop items from the heap (which will naturally update the heap).
+//
+// If you are updating items in the heap, please note this method does *not* reheapify.
+//
+// This method is not concurrency safe. For concurrent applications, consider using a mutex, or pull the data out using Items().
+func (heap *MaxBinaryHeap[T]) Iterator() iter.Seq[T] {
+	return func(yield func(T) bool) {
+		for index := 0; index < len(heap.heapData); index += 1 {
+			item := heap.heapData[index]
+			if !yield(item) {
+				break
+			}
+		}
+	}
+}

heap/MaxBinaryHeap/maxBinaryHeap_apply_test.go

@@ -70,3 +70,16 @@ func TestMaxBinaryHeapFold(t *testing.T) {
 		t.Errorf("expected all items to be contained in ground truth array")
 	}
 }
+
+func TestMaxBinaryIterator(t *testing.T) {
+	heap := maxbinaryheap.New[string](comparator.DefaultStringComparator)
+	items := []string{"a", "b", "c", "d", "e", "f", "g", "h"}
+	for _, item := range items {
+		heap.Add(item)
+	}
+
+	concatString := ""
+	for item := range heap.Iterator() {
+		concatString += item
+	}
+}

heap/MinBinaryHeap/minBinaryHeap.go

@@ -1,6 +1,8 @@
 package minbinaryheap
 
 import (
+	"iter"
+
 	comparator "github.com/hmcalister/Go-DSA/utils/Comparator"
 	dsa_error "github.com/hmcalister/Go-DSA/utils/DSA_Error"
 )
@@ -249,3 +251,22 @@ func Fold[T any, G any](heap *MinBinaryHeap[T], initialAccumulator G, f func(ite
 
 	return accumulator
 }
+
+// Iterate over the items of the heap.
+// In case it matters, the iteration is effectively in "reading order" along the heap.
+// This is *not* a sorted order. To iterate in sorted order you may either extract the heap items with Items() and sort,
+// or continually pop items from the heap (which will naturally update the heap).
+//
+// If you are updating items in the heap, please note this method does *not* reheapify.
+//
+// This method is not concurrency safe. For concurrent applications, consider using a mutex, or pull the data out using Items().
+func (heap *MinBinaryHeap[T]) Iterator() iter.Seq[T] {
+	return func(yield func(T) bool) {
+		for index := 0; index < len(heap.heapData); index += 1 {
+			item := heap.heapData[index]
+			if !yield(item) {
+				break
+			}
+		}
+	}
+}

heap/MinBinaryHeap/minBinaryHeap_apply_test.go

@@ -27,6 +27,7 @@ func TestMinBinaryHeapApply(t *testing.T) {
 		t.Errorf("result (%v) does not match expected result (%v)", concatString, expectedConcatString)
 	}
 }
+
 func TestMinBinaryHeapMap(t *testing.T) {
 	heap := minbinaryheap.New[string](comparator.DefaultStringComparator)
 	items := []string{"a", "b", "c", "d", "e", "f", "g", "h"}
@@ -78,3 +79,25 @@ func TestMinBinaryHeapFold(t *testing.T) {
 		t.Errorf("expected all items to be contained in ground truth array")
 	}
 }
+
+func TestMinBinaryIterator(t *testing.T) {
+	heap := minbinaryheap.New[string](comparator.DefaultStringComparator)
+	items := []string{"a", "b", "c", "d", "e", "f", "g", "h"}
+	for _, item := range items {
+		heap.Add(item)
+	}
+
+	concatString := ""
+	for item := range heap.Iterator() {
+		concatString += item
+	}
+
+	expectedConcatString := ""
+	for _, item := range items {
+		expectedConcatString += item
+	}
+
+	if concatString != expectedConcatString {
+		t.Errorf("result (%v) does not match expected result (%v)", concatString, expectedConcatString)
+	}
+}

list/LinkedList/linkedlist.go

@@ -1,6 +1,10 @@
 package linkedlist
 
-import dsa_error "github.com/hmcalister/Go-DSA/utils/DSA_Error"
+import (
+	"iter"
+
+	dsa_error "github.com/hmcalister/Go-DSA/utils/DSA_Error"
+)
 
 // An implementation of a doubly linked list.
 type LinkedList[T any] struct {
@@ -232,6 +236,40 @@ func ReverseFold[T any, G any](list *LinkedList[T], initialAccumulator G, f func
 	return acc
 }
 
+// Iterate over the items of the list in the forward direction.
+// Returns both the index (as counted from the head) and item.
+// This method is not concurrency safe. For concurrent applications, consider using a mutex, or pull the data out using Items().
+func (list *LinkedList[T]) ForwardIterator() iter.Seq2[int, T] {
+	return func(yield func(int, T) bool) {
+		index := 0
+		currentNode := list.head
+		for currentNode != nil {
+			if !yield(index, currentNode.item) {
+				return
+			}
+			currentNode = currentNode.next
+			index += 1
+		}
+	}
+}
+
+// Iterate over the items of the list in the reverse direction.
+// Returns both the index (as counted from the tail) and item.
+// This method is not concurrency safe. For concurrent applications, consider using a mutex, or pull the data out using Items().
+func (list *LinkedList[T]) ReverseIterator() iter.Seq2[int, T] {
+	return func(yield func(int, T) bool) {
+		index := 0
+		currentNode := list.tail
+		for currentNode != nil {
+			if !yield(index, currentNode.item) {
+				return
+			}
+			currentNode = currentNode.prev
+			index += 1
+		}
+	}
+}
+
 // ----------------------------------------------------------------------------
 // Add methods
 

list/LinkedList/linkedlist_apply_test.go

@@ -135,3 +135,48 @@ func TestReverseFold(t *testing.T) {
 		t.Errorf("result (%v) does not match expected result (%v)", concatString, expectedConcatString)
 	}
 }
+
+func TestForwardIterator(t *testing.T) {
+	list := linkedlist.New[int]()
+	items := []int{1, 2, 3, 4, 5, 6, 7, 8, 9}
+	for _, item := range items {
+		list.Add(item)
+	}
+
+	sum := 0
+	for index, item := range list.ForwardIterator() {
+		sum += index * item
+	}
+
+	expectedSum := 0
+	for index, item := range items {
+		expectedSum += index * item
+	}
+
+	if sum != expectedSum {
+		t.Errorf("result (%v) does not match expected result (%v)", sum, expectedSum)
+	}
+}
+
+func TestReverseIterator(t *testing.T) {
+	list := linkedlist.New[int]()
+	items := []int{1, 2, 3, 4, 5, 6, 7, 8, 9}
+	for _, item := range items {
+		list.Add(item)
+	}
+
+	sum := 0
+	for index, item := range list.ReverseIterator() {
+		sum += index * item
+	}
+
+	slices.Reverse(items)
+	expectedSum := 0
+	for index, item := range items {
+		expectedSum += index * item
+	}
+
+	if sum != expectedSum {
+		t.Errorf("result (%v) does not match expected result (%v)", sum, expectedSum)
+	}
+}

queue/ArrayQueue/arrayqueue.go

@@ -1,6 +1,8 @@
 package arrayqueue
 
 import (
+	"iter"
+
 	dsa_error "github.com/hmcalister/Go-DSA/utils/DSA_Error"
 )
 
@@ -181,3 +183,31 @@ func ReverseFold[T any, G any](queue *ArrayQueue[T], initialAccumulator G, f fun
 
 	return accumulator
 }
+
+// Iterate over the items of the queue in the forward direction (front to back).
+// Returns both the index (as counted from the front of the queue) and item.
+// This method is not concurrency safe. For concurrent applications, consider using a mutex, or pull the data out using Items().
+func (queue *ArrayQueue[T]) ForwardIterator() iter.Seq2[int, T] {
+	return func(yield func(int, T) bool) {
+		for index := 0; index < len(queue.queueData); index += 1 {
+			item := queue.queueData[index]
+			if !yield(index, item) {
+				break
+			}
+		}
+	}
+}
+
+// Iterate over the items of the queue in the reverse direction (back to front).
+// Returns both the index (as counted from the back of the queue) and item.
+// This method is not concurrency safe. For concurrent applications, consider using a mutex, or pull the data out using Items().
+func (queue *ArrayQueue[T]) ReverseIterator() iter.Seq2[int, T] {
+	return func(yield func(int, T) bool) {
+		for index := 0; index < len(queue.queueData); index += 1 {
+			item := queue.queueData[len(queue.queueData)-index-1]
+			if !yield(index, item) {
+				break
+			}
+		}
+	}
+}

queue/ArrayQueue/arrayqueue_apply_test.go

@@ -120,3 +120,48 @@ func TestReverseFold(t *testing.T) {
 		t.Errorf("result (%v) does not match expected result (%v)", concatString, expectedConcatString)
 	}
 }
+
+func TestForwardIterator(t *testing.T) {
+	queue := arrayqueue.New[int]()
+	items := []int{1, 2, 3, 4, 5, 6, 7, 8, 9}
+	for _, item := range items {
+		queue.Add(item)
+	}
+
+	sum := 0
+	for index, item := range queue.ForwardIterator() {
+		sum += index * item
+	}
+
+	expectedSum := 0
+	for index, item := range items {
+		expectedSum += index * item
+	}
+
+	if sum != expectedSum {
+		t.Errorf("result (%v) does not match expected result (%v)", sum, expectedSum)
+	}
+}
+
+func TestReverseIterator(t *testing.T) {
+	queue := arrayqueue.New[int]()
+	items := []int{1, 2, 3, 4, 5, 6, 7, 8, 9}
+	for _, item := range items {
+		queue.Add(item)
+	}
+
+	sum := 0
+	for index, item := range queue.ReverseIterator() {
+		sum += index * item
+	}
+
+	slices.Reverse(items)
+	expectedSum := 0
+	for index, item := range items {
+		expectedSum += index * item
+	}
+
+	if sum != expectedSum {
+		t.Errorf("result (%v) does not match expected result (%v)", sum, expectedSum)
+	}
+}

queue/LinkedListQueue/linkedlistqueue.go

@@ -1,6 +1,8 @@
 package linkedlistqueue
 
 import (
+	"iter"
+
 	linkedlist "github.com/hmcalister/Go-DSA/list/LinkedList"
 	dsa_error "github.com/hmcalister/Go-DSA/utils/DSA_Error"
 )
@@ -158,3 +160,17 @@ func ReverseMap[T any](queue *LinkedListQueue[T], f func(item T) T) {
 func ReverseFold[T any, G any](queue *LinkedListQueue[T], initialAccumulator G, f func(item T, accumulator G) G) G {
 	return linkedlist.ReverseFold(queue.queueData, initialAccumulator, f)
 }
+
+// Iterate over the items of the queue in the forward direction (front to back).
+// Returns both the index (from the front of the queue) and item.
+// This method is not concurrency safe. For concurrent applications, consider using a mutex, or pull the data out using Items().
+func (queue *LinkedListQueue[T]) ForwardIterator() iter.Seq2[int, T] {
+	return queue.queueData.ForwardIterator()
+}
+
+// Iterate over the items of the queue in the reverse direction (top to bottom).
+// Returns both the index from the back of the queue) and item.
+// This method is not concurrency safe. For concurrent applications, consider using a mutex, or pull the data out using Items().
+func (queue *LinkedListQueue[T]) ReverseIterator() iter.Seq2[int, T] {
+	return queue.queueData.ReverseIterator()
+}

queue/LinkedListQueue/linkedlistqueue_apply_test.go

@@ -120,3 +120,48 @@ func TestReverseFold(t *testing.T) {
 		t.Errorf("result (%v) does not match expected result (%v)", concatString, expectedConcatString)
 	}
 }
+
+func TestForwardIterator(t *testing.T) {
+	queue := linkedlistqueue.New[int]()
+	items := []int{1, 2, 3, 4, 5, 6, 7, 8, 9}
+	for _, item := range items {
+		queue.Add(item)
+	}
+
+	sum := 0
+	for index, item := range queue.ForwardIterator() {
+		sum += index * item
+	}
+
+	expectedSum := 0
+	for index, item := range items {
+		expectedSum += index * item
+	}
+
+	if sum != expectedSum {
+		t.Errorf("result (%v) does not match expected result (%v)", sum, expectedSum)
+	}
+}
+
+func TestReverseIterator(t *testing.T) {
+	queue := linkedlistqueue.New[int]()
+	items := []int{1, 2, 3, 4, 5, 6, 7, 8, 9}
+	for _, item := range items {
+		queue.Add(item)
+	}
+
+	sum := 0
+	for index, item := range queue.ReverseIterator() {
+		sum += index * item
+	}
+
+	slices.Reverse(items)
+	expectedSum := 0
+	for index, item := range items {
+		expectedSum += index * item
+	}
+
+	if sum != expectedSum {
+		t.Errorf("result (%v) does not match expected result (%v)", sum, expectedSum)
+	}
+}