feat(linked): add linked queue implementation with tests

Author: adrianbrad

CHANGELOG.md

@@ -1,5 +1,7 @@
 ## v1.2.1 (2023-05-08)
 
+### Fix
+
 - fix a bug caused by not calling the (*sync.Cond).Wait() method in a loop
 
 ## v1.2.0 (2023-04-14)

README.md

@@ -33,6 +33,7 @@ Benchmarks and Example tests can be found in this package.
     * [Blocking Queue](#blocking-queue)
     * [Priority Queue](#priority-queue)
     * [Circular Queue](#circular-queue)
+    * [Linked Queue](#linked-queue)
   * [Benchmarks](#benchmarks-)
 <!-- TOC -->
 
@@ -221,18 +222,64 @@ func main() {
 }
 ```
 
+### Linked Queue
+
+A linked queue, implemented as a singly linked list, offering O(1)
+time complexity for enqueue and dequeue operations. The queue maintains pointers
+to both the head (front) and tail (end) of the list for efficient operations
+without the need for traversal.
+
+```go
+package main
+
+import (
+  "fmt"
+
+  "github.com/adrianbrad/queue"
+)
+
+func main() {
+  elems := []int{2, 3, 4}
+
+  circularQueue := queue.NewLinked(elems)
+
+  containsTwo := circularQueue.Contains(2)
+  fmt.Println(containsTwo) // true
+
+  size := circularQueue.Size()
+  fmt.Println(size) // 3
+
+  empty := circularQueue.IsEmpty()
+  fmt.Println(empty) // false
+
+  if err := circularQueue.Offer(1); err != nil {
+    // handle err
+  }
+
+  elem, err := circularQueue.Get()
+  if err != nil {
+    // handle err
+  }
+
+  fmt.Printf("elem: %d\n", elem) // elem: 2
+}
+```
+
 ## Benchmarks 
 
-Results as of April 2023.
+Results as of October 2023.
 
 ```text
-BenchmarkBlockingQueue/Peek-12          72900492                18.92 ns/op            0 B/op          0 allocs/op
-BenchmarkBlockingQueue/Get_Offer-12     14937858                95.08 ns/op           41 B/op          0 allocs/op
-BenchmarkBlockingQueue/Offer-12         26680512                51.81 ns/op           45 B/op          0 allocs/op
-BenchmarkCircularQueue/Peek-12          73749498                16.24 ns/op            0 B/op          0 allocs/op
-BenchmarkCircularQueue/Get_Offer-12     18768650                63.02 ns/op            0 B/op          0 allocs/op
-BenchmarkCircularQueue/Offer-12         38328231                37.57 ns/op            0 B/op          0 allocs/op
-BenchmarkPriorityQueue/Peek-12          75156879                15.79 ns/op            0 B/op          0 allocs/op
-BenchmarkPriorityQueue/Get_Offer-12     17643837                68.65 ns/op            0 B/op          0 allocs/op
-BenchmarkPriorityQueue/Offer-12         20506784                57.43 ns/op           54 B/op          0 allocs/op
+BenchmarkBlockingQueue/Peek-8           84873882                13.98 ns/op            0 B/op          0 allocs/op
+BenchmarkBlockingQueue/Get_Offer-8      27135865                47.00 ns/op           44 B/op          0 allocs/op
+BenchmarkBlockingQueue/Offer-8          53750395                25.40 ns/op           43 B/op          0 allocs/op
+BenchmarkCircularQueue/Peek-8           86001980                13.76 ns/op            0 B/op          0 allocs/op
+BenchmarkCircularQueue/Get_Offer-8      32379159                36.83 ns/op            0 B/op          0 allocs/op
+BenchmarkCircularQueue/Offer-8          63956366                18.77 ns/op            0 B/op          0 allocs/op
+BenchmarkLinkedQueue/Peek-8             1000000000              0.4179 ns/op           0 B/op          0 allocs/op
+BenchmarkLinkedQueue/Get_Offer-8        61257436                18.48 ns/op           16 B/op          1 allocs/op
+BenchmarkLinkedQueue/Offer-8            38975062                30.74 ns/op           16 B/op          1 allocs/op
+BenchmarkPriorityQueue/Peek-8           86633734                14.02 ns/op            0 B/op          0 allocs/op
+BenchmarkPriorityQueue/Get_Offer-8      29347177                39.88 ns/op            0 B/op          0 allocs/op
+BenchmarkPriorityQueue/Offer-8          40117958                31.37 ns/op           54 B/op          0 allocs/op
 ```

doc.go

@@ -12,4 +12,9 @@
 // A circular queue, which is a queue that uses a fixed-size slice as
 // if it were connected end-to-end. When the queue is full, adding a new element to the queue
 // overwrites the oldest element.
+//
+// A linked queue, implemented as a singly linked list, offering O(1)
+// time complexity for enqueue and dequeue operations. The queue maintains pointers
+// to both the head (front) and tail (end) of the list for efficient operations
+// without the need for traversal.
 package queue

example_linked_test.go

@@ -0,0 +1,56 @@
+package queue_test
+
+import (
+	"fmt"
+
+	"github.com/adrianbrad/queue"
+)
+
+func ExampleLinked() {
+	elems := []int{2, 4, 1}
+
+	priorityQueue := queue.NewLinked(
+		elems,
+	)
+
+	containsTwo := priorityQueue.Contains(2)
+	fmt.Println("Contains 2:", containsTwo)
+
+	size := priorityQueue.Size()
+	fmt.Println("Size:", size)
+
+	if err := priorityQueue.Offer(3); err != nil {
+		fmt.Println("Offer err: ", err)
+		return
+	}
+
+	empty := priorityQueue.IsEmpty()
+	fmt.Println("Empty before clear:", empty)
+
+	clearElems := priorityQueue.Clear()
+	fmt.Println("Clear:", clearElems)
+
+	empty = priorityQueue.IsEmpty()
+	fmt.Println("Empty after clear:", empty)
+
+	if err := priorityQueue.Offer(5); err != nil {
+		fmt.Println("Offer err: ", err)
+		return
+	}
+
+	elem, err := priorityQueue.Get()
+	if err != nil {
+		fmt.Println("Get err: ", err)
+		return
+	}
+
+	fmt.Println("Get:", elem)
+
+	// Output:
+	// Contains 2: true
+	// Size: 3
+	// Empty before clear: false
+	// Clear: [2 4 1 3]
+	// Empty after clear: true
+	// Get: 5
+}

linked.go

@@ -0,0 +1,152 @@
+package queue
+
+var _ Queue[any] = (*Linked[any])(nil)
+
+// node is an individual element of the linked list.
+type node[T any] struct {
+	value T
+	next  *node[T]
+}
+
+// Linked represents a data structure representing a queue that uses a
+// linked list for its internal storage.
+// ! The Linked Queue is not thread safe.
+type Linked[T comparable] struct {
+	head *node[T] // first node of the queue.
+	tail *node[T] // last node of the queue.
+	size int      // number of elements in the queue.
+	// nolint: revive
+	initialElements []T // initial elements with which the queue was created, allowing for a reset to its original state if needed.
+}
+
+// NewLinked creates a new Linked containing the given elements.
+func NewLinked[T comparable](elements []T) *Linked[T] {
+	queue := &Linked[T]{
+		head:            nil,
+		tail:            nil,
+		size:            0,
+		initialElements: make([]T, len(elements)),
+	}
+
+	copy(queue.initialElements, elements)
+
+	for _, element := range elements {
+		_ = queue.Offer(element)
+	}
+
+	return queue
+}
+
+// Get retrieves and removes the head of the queue.
+func (q *Linked[T]) Get() (elem T, _ error) {
+	if q.IsEmpty() {
+		return elem, ErrNoElementsAvailable
+	}
+
+	value := q.head.value
+	q.head = q.head.next
+	q.size--
+
+	if q.IsEmpty() {
+		q.tail = nil
+	}
+
+	return value, nil
+}
+
+// Offer inserts the element into the queue.
+func (q *Linked[T]) Offer(value T) error {
+	newNode := &node[T]{value: value}
+
+	if q.IsEmpty() {
+		q.head = newNode
+	} else {
+		q.tail.next = newNode
+	}
+
+	q.tail = newNode
+	q.size++
+
+	return nil
+}
+
+// Reset sets the queue to its initial state.
+func (q *Linked[T]) Reset() {
+	q.head = nil
+	q.tail = nil
+	q.size = 0
+
+	for _, element := range q.initialElements {
+		_ = q.Offer(element)
+	}
+}
+
+// Contains returns true if the queue contains the element.
+func (q *Linked[T]) Contains(value T) bool {
+	current := q.head
+	for current != nil {
+		if current.value == value {
+			return true
+		}
+
+		current = current.next
+	}
+
+	return false
+}
+
+// Peek retrieves but does not remove the head of the queue.
+func (q *Linked[T]) Peek() (elem T, _ error) {
+	if q.IsEmpty() {
+		return elem, ErrNoElementsAvailable
+	}
+
+	return q.head.value, nil
+}
+
+// Size returns the number of elements in the queue.
+func (q *Linked[T]) Size() int {
+	return q.size
+}
+
+// IsEmpty returns true if the queue is empty, false otherwise.
+func (q *Linked[T]) IsEmpty() bool {
+	return q.size == 0
+}
+
+// Iterator returns a channel that will be filled with the elements.
+// It removes the elements from the queue.
+func (q *Linked[T]) Iterator() <-chan T {
+	ch := make(chan T)
+
+	elems := q.Clear()
+
+	go func() {
+		for _, e := range elems {
+			ch <- e
+		}
+
+		close(ch)
+	}()
+
+	return ch
+}
+
+// Clear removes and returns all elements from the queue.
+func (q *Linked[T]) Clear() []T {
+	elements := make([]T, 0, q.size)
+
+	current := q.head
+	for current != nil {
+		elements = append(elements, current.value)
+		next := current.next
+		current = next
+	}
+
+	// Clear the queue
+	q.head = nil
+	q.tail = nil
+	q.size = 0
+
+	return elements
+}