Merge pull request #202 from emirpasic/development

Implements queues, LinkedListQueue and ArrayQueue

Author: emirpasic

README.md

@@ -36,6 +36,9 @@ Implementation of various data structures and algorithms in Go.
     - [AVLTree](#avltree)
     - [BTree](#btree)
     - [BinaryHeap](#binaryheap)
+  - [Queues](#queues)
+    - [LinkedListQueue](#linkedlistqueue)
+    - [ArrayQueue](#arrayqueue)
 - [Functions](#functions)
     - [Comparator](#comparator)
     - [Iterator](#iterator)
@@ -94,6 +97,9 @@ Containers are either ordered or unordered. All ordered containers provide [stat
 |   | [AVLTree](#avltree) | yes | yes* | no | key |
 |   | [BTree](#btree) | yes | yes* | no | key |
 |   | [BinaryHeap](#binaryheap) | yes | yes* | no | index |
+| [Queues](#queues) |
+|   | [LinkedListQueue](#linkedlistqueue) | yes | yes | no | index |
+|   | [ArrayQueue](#arrayqueue) | yes | yes* | no | index |
 |   |  |  | <sub><sup>*reversible</sup></sub> |  | <sub><sup>*bidirectional</sup></sub> |
 
 ### Lists
@@ -126,7 +132,7 @@ type List interface {
 
 A [list](#lists) backed by a dynamic array that grows and shrinks implicitly.
 
-Implements [List](#lists), [IteratorWithIndex](#iteratorwithindex), [EnumerableWithIndex](#enumerablewithindex), [JSONSerializer](#jsonserializer) and [JSONDeserializer](#jsondeserializer) interfaces.
+Implements [List](#lists), [ReverseIteratorWithIndex](#reverseiteratorwithindex), [EnumerableWithIndex](#enumerablewithindex), [JSONSerializer](#jsonserializer) and [JSONDeserializer](#jsondeserializer) interfaces.
 
 ```go
 package main
@@ -200,7 +206,7 @@ func main() {
 
 A [list](#lists) where each element points to the next and previous elements in the list.
 
-Implements [List](#lists), [IteratorWithIndex](#iteratorwithindex), [EnumerableWithIndex](#enumerablewithindex), [JSONSerializer](#jsonserializer) and [JSONDeserializer](#jsondeserializer) interfaces.
+Implements [List](#lists), [ReverseIteratorWithIndex](#reverseiteratorwithindex), [EnumerableWithIndex](#enumerablewithindex), [JSONSerializer](#jsonserializer) and [JSONDeserializer](#jsondeserializer) interfaces.
 
 ```go
 package main
@@ -290,7 +296,7 @@ func main() {
 
 A [set](#sets) backed by a [red-black tree](#redblacktree) to keep the elements ordered with respect to the [comparator](#comparator).
 
-Implements [Set](#sets), [IteratorWithIndex](#iteratorwithindex), [EnumerableWithIndex](#enumerablewithindex), [JSONSerializer](#jsonserializer) and [JSONDeserializer](#jsondeserializer) interfaces.
+Implements [Set](#sets), [ReverseIteratorWithIndex](#reverseiteratorwithindex), [EnumerableWithIndex](#enumerablewithindex), [JSONSerializer](#jsonserializer) and [JSONDeserializer](#jsondeserializer) interfaces.
 
 ```go
 package main
@@ -317,7 +323,7 @@ func main() {
 
 A [set](#sets) that preserves insertion-order. Data structure is backed by a hash table to store values and [doubly-linked list](#doublylinkedlist) to store insertion ordering.
 
-Implements [Set](#sets), [IteratorWithIndex](#iteratorwithindex), [EnumerableWithIndex](#enumerablewithindex), [JSONSerializer](#jsonserializer) and [JSONDeserializer](#jsondeserializer) interfaces.
+Implements [Set](#sets), [ReverseIteratorWithIndex](#reverseiteratorwithindex), [EnumerableWithIndex](#enumerablewithindex), [JSONSerializer](#jsonserializer) and [JSONDeserializer](#jsondeserializer) interfaces.
 
 ```go
 package main
@@ -479,7 +485,7 @@ func main() {
 
 A [map](#maps) based on [red-black tree](#redblacktree). Keys are ordered with respect to the [comparator](#comparator).
 
-Implements [Map](#maps), [IteratorWithKey](#iteratorwithkey), [EnumerableWithKey](#enumerablewithkey), [JSONSerializer](#jsonserializer) and [JSONDeserializer](#jsondeserializer) interfaces.
+Implements [Map](#maps), [ReverseIteratorWithIndex](#reverseiteratorwithindex), [EnumerableWithKey](#enumerablewithkey), [JSONSerializer](#jsonserializer) and [JSONDeserializer](#jsondeserializer) interfaces.
 
 ```go
 package main
@@ -510,7 +516,7 @@ func main() {
 
 A [map](#maps) that preserves insertion-order. It is backed by a hash table to store values and [doubly-linked list](doublylinkedlist) to store ordering.
 
-Implements [Map](#maps), [IteratorWithKey](#iteratorwithkey), [EnumerableWithKey](#enumerablewithkey), [JSONSerializer](#jsonserializer) and [JSONDeserializer](#jsondeserializer) interfaces.
+Implements [Map](#maps), [ReverseIteratorWithIndex](#reverseiteratorwithindex), [EnumerableWithKey](#enumerablewithkey), [JSONSerializer](#jsonserializer) and [JSONDeserializer](#jsondeserializer) interfaces.
 
 ```go
 package main
@@ -567,7 +573,7 @@ func main() {
 
 A [map](#maps) based on red-black tree. This map guarantees that the map will be in both ascending key and value order.  Other than key and value ordering, the goal with this structure is to avoid duplication of elements (unlike in [HashBidiMap](#hashbidimap)), which can be significant if contained elements are large.
 
-Implements [BidiMap](#maps), [IteratorWithKey](#iteratorwithkey), [EnumerableWithKey](#enumerablewithkey), [JSONSerializer](#jsonserializer) and [JSONDeserializer](#jsondeserializer) interfaces.
+Implements [BidiMap](#maps), [ReverseIteratorWithIndex](#reverseiteratorwithindex), [EnumerableWithKey](#enumerablewithkey), [JSONSerializer](#jsonserializer) and [JSONDeserializer](#jsondeserializer) interfaces.
 
 ```go
 package main
@@ -864,6 +870,85 @@ func main() {
 }
 ```
 
+### Queues
+
+A queue that represents a first-in-first-out (FIFO) data structure. The usual enqueue and dequeue operations are provided, as well as a method to peek at the first item in the queue.
+
+<p align="center"><img src="https://upload.wikimedia.org/wikipedia/commons/thumb/5/52/Data_Queue.svg/300px-Data_Queue.svg.png" width="200px" height="120px" /></p>
+
+Implements [Container](#containers) interface.
+
+```go
+type Queue interface {
+	Enqueue(value interface{})
+	Dequeue() (value interface{}, ok bool)
+	Peek() (value interface{}, ok bool)
+
+	containers.Container
+	// Empty() bool
+	// Size() int
+	// Clear()
+	// Values() []interface{}
+	// String() string
+}
+```
+
+#### LinkedListQueue
+
+A [queue](#queues) based on a [linked list](#singlylinkedlist).
+
+Implements [Queue](#queues), [IteratorWithIndex](#iteratorwithindex), [JSONSerializer](#jsonserializer) and [JSONDeserializer](#jsondeserializer) interfaces.
+
+```go
+package main
+
+import llq "github.com/emirpasic/gods/queues/linkedlistqueue"
+
+// LinkedListQueueExample to demonstrate basic usage of LinkedListQueue
+func main() {
+    queue := llq.New()     // empty
+    queue.Enqueue(1)       // 1
+    queue.Enqueue(2)       // 1, 2
+    _ = queue.Values()     // 1, 2 (FIFO order)
+    _, _ = queue.Peek()    // 1,true
+    _, _ = queue.Dequeue() // 1, true
+    _, _ = queue.Dequeue() // 2, true
+    _, _ = queue.Dequeue() // nil, false (nothing to deque)
+    queue.Enqueue(1)       // 1
+    queue.Clear()          // empty
+    queue.Empty()          // true
+    _ = queue.Size()       // 0
+}
+```
+
+#### ArrayQueue
+
+A [queue](#queues) based on a [array list](#arraylist).
+
+Implements [Queue](#queues), [ReverseIteratorWithIndex](#iteratorwithindex), [JSONSerializer](#jsonserializer) and [JSONDeserializer](#jsondeserializer) interfaces.
+
+```go
+package main
+
+import aq "github.com/emirpasic/gods/queues/arrayqueue"
+
+// ArrayQueueExample to demonstrate basic usage of ArrayQueue
+func main() {
+    queue := aq.New()      // empty
+    queue.Enqueue(1)       // 1
+    queue.Enqueue(2)       // 1, 2
+    _ = queue.Values()     // 1, 2 (FIFO order)
+    _, _ = queue.Peek()    // 1,true
+    _, _ = queue.Dequeue() // 1, true
+    _, _ = queue.Dequeue() // 2, true
+    _, _ = queue.Dequeue() // nil, false (nothing to deque)
+    queue.Enqueue(1)       // 1
+    queue.Clear()          // empty
+    queue.Empty()          // true
+    _ = queue.Size()       // 0
+}
+```
+
 ## Functions
 
 Various helper functions used throughout the library.

examples/arrayqueue/arrayqqueue.go

@@ -0,0 +1,23 @@
+// Copyright (c) 2015, Emir Pasic. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package main
+
+import aq "github.com/emirpasic/gods/queues/arrayqueue"
+
+// ArrayQueueExample to demonstrate basic usage of ArrayQueue
+func main() {
+	queue := aq.New()      // empty
+	queue.Enqueue(1)       // 1
+	queue.Enqueue(2)       // 1, 2
+	_ = queue.Values()     // 1, 2 (FIFO order)
+	_, _ = queue.Peek()    // 1,true
+	_, _ = queue.Dequeue() // 1, true
+	_, _ = queue.Dequeue() // 2, true
+	_, _ = queue.Dequeue() // nil, false (nothing to deque)
+	queue.Enqueue(1)       // 1
+	queue.Clear()          // empty
+	queue.Empty()          // true
+	_ = queue.Size()       // 0
+}

examples/linkedlistqueue/linkedlistqueue.go

@@ -0,0 +1,23 @@
+// Copyright (c) 2015, Emir Pasic. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package main
+
+import llq "github.com/emirpasic/gods/queues/linkedlistqueue"
+
+// LinkedListQueueExample to demonstrate basic usage of LinkedListQueue
+func main() {
+	queue := llq.New()     // empty
+	queue.Enqueue(1)       // 1
+	queue.Enqueue(2)       // 1, 2
+	_ = queue.Values()     // 1, 2 (FIFO order)
+	_, _ = queue.Peek()    // 1,true
+	_, _ = queue.Dequeue() // 1, true
+	_, _ = queue.Dequeue() // 2, true
+	_, _ = queue.Dequeue() // nil, false (nothing to deque)
+	queue.Enqueue(1)       // 1
+	queue.Clear()          // empty
+	queue.Empty()          // true
+	_ = queue.Size()       // 0
+}

lists/lists.go

@@ -30,4 +30,5 @@ type List interface {
 	// Size() int
 	// Clear()
 	// Values() []interface{}
+	// String() string
 }

maps/maps.go

@@ -29,6 +29,7 @@ type Map interface {
 	// Size() int
 	// Clear()
 	// Values() []interface{}
+	// String() string
 }
 
 // BidiMap interface that all bidirectional maps implement (extends the Map interface)

queues/arrayqueue/arrayqueue.go

@@ -0,0 +1,88 @@
+// Copyright (c) 2021, Aryan Ahadinia. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// Package arrayqueue implements a queue backed by array list.
+//
+// Structure is not thread safe.
+//
+// Reference: https://en.wikipedia.org/wiki/Queue_(abstract_data_type)
+package arrayqueue
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/emirpasic/gods/lists/arraylist"
+	"github.com/emirpasic/gods/queues"
+)
+
+// Assert Queue implementation
+var _ queues.Queue = (*Queue)(nil)
+
+// Queue holds elements in an array-list
+type Queue struct {
+	list *arraylist.List
+}
+
+// New instantiates a new empty queue
+func New() *Queue {
+	return &Queue{list: arraylist.New()}
+}
+
+// Enqueue adds a value to the end of the queue
+func (queue *Queue) Enqueue(value interface{}) {
+	queue.list.Add(value)
+}
+
+// Dequeue removes first element of the queue and returns it, or nil if queue is empty.
+// Second return parameter is true, unless the queue was empty and there was nothing to dequeue.
+func (queue *Queue) Dequeue() (value interface{}, ok bool) {
+	value, ok = queue.list.Get(0)
+	if ok {
+		queue.list.Remove(0)
+	}
+	return
+}
+
+// Peek returns first element of the queue without removing it, or nil if queue is empty.
+// Second return parameter is true, unless the queue was empty and there was nothing to peek.
+func (queue *Queue) Peek() (value interface{}, ok bool) {
+	return queue.list.Get(0)
+}
+
+// Empty returns true if queue does not contain any elements.
+func (queue *Queue) Empty() bool {
+	return queue.list.Empty()
+}
+
+// Size returns number of elements within the queue.
+func (queue *Queue) Size() int {
+	return queue.list.Size()
+}
+
+// Clear removes all elements from the queue.
+func (queue *Queue) Clear() {
+	queue.list.Clear()
+}
+
+// Values returns all elements in the queue (FIFO order).
+func (queue *Queue) Values() []interface{} {
+	return queue.list.Values()
+}
+
+// String returns a string representation of container
+func (queue *Queue) String() string {
+	str := "ArrayQueue\n"
+	values := []string{}
+	for _, value := range queue.list.Values() {
+		values = append(values, fmt.Sprintf("%v", value))
+	}
+	str += strings.Join(values, ", ")
+	return str
+}
+
+// Check that the index is within bounds of the list
+func (queue *Queue) withinRange(index int) bool {
+	return index >= 0 && index < queue.list.Size()
+}