github.com/songzhibin97/go-baseutils@v0.0.2-0.20240302024150-487d8ce9c082/structure/queues/priorityqueue/priorityqueue.go (about)

     1  // Package priorityqueue implements a priority queue backed by binary queue.
     2  //
     3  // An unbounded priority queue based on a priority queue.
     4  // The elements of the priority queue are ordered by a comparator provided at queue construction time.
     5  //
     6  // The heap of this queue is the least/smallest element with respect to the specified ordering.
     7  // If multiple elements are tied for least value, the heap is one of those elements arbitrarily.
     8  //
     9  // Structure is not thread safe.
    10  //
    11  // References: https://en.wikipedia.org/wiki/Priority_queue
    12  package priorityqueue
    13  
    14  import (
    15  	"fmt"
    16  	"strings"
    17  
    18  	"github.com/songzhibin97/go-baseutils/base/bcomparator"
    19  	"github.com/songzhibin97/go-baseutils/structure/queues"
    20  	"github.com/songzhibin97/go-baseutils/structure/trees/binaryheap"
    21  )
    22  
    23  // Assert Queue implementation
    24  var _ queues.Queue[any] = (*Queue[any])(nil)
    25  
    26  // Queue holds elements in an array-list
    27  type Queue[E any] struct {
    28  	heap       *binaryheap.Heap[E]
    29  	Comparator bcomparator.Comparator[E]
    30  }
    31  
    32  // NewWith instantiates a new empty queue with the custom comparator.
    33  func NewWith[E any](comparator bcomparator.Comparator[E]) *Queue[E] {
    34  	return &Queue[E]{heap: binaryheap.NewWith(comparator), Comparator: comparator}
    35  }
    36  
    37  // Enqueue adds a value to the end of the queue
    38  func (queue *Queue[E]) Enqueue(value E) {
    39  	queue.heap.Push(value)
    40  }
    41  
    42  // Dequeue removes first element of the queue and returns it, or nil if queue is empty.
    43  // Second return parameter is true, unless the queue was empty and there was nothing to dequeue.
    44  func (queue *Queue[E]) Dequeue() (value E, ok bool) {
    45  	return queue.heap.Pop()
    46  }
    47  
    48  // Peek returns top element on the queue without removing it, or nil if queue is empty.
    49  // Second return parameter is true, unless the queue was empty and there was nothing to peek.
    50  func (queue *Queue[E]) Peek() (value E, ok bool) {
    51  	return queue.heap.Peek()
    52  }
    53  
    54  // Empty returns true if queue does not contain any elements.
    55  func (queue *Queue[E]) Empty() bool {
    56  	return queue.heap.Empty()
    57  }
    58  
    59  // Size returns number of elements within the queue.
    60  func (queue *Queue[E]) Size() int {
    61  	return queue.heap.Size()
    62  }
    63  
    64  // Clear removes all elements from the queue.
    65  func (queue *Queue[E]) Clear() {
    66  	queue.heap.Clear()
    67  }
    68  
    69  // Values returns all elements in the queue.
    70  func (queue *Queue[E]) Values() []E {
    71  	return queue.heap.Values()
    72  }
    73  
    74  // String returns a string representation of container
    75  func (queue *Queue[E]) String() string {
    76  	b := strings.Builder{}
    77  	b.WriteString("PriorityQueue\n")
    78  	for index, value := range queue.Values() {
    79  		b.WriteString(fmt.Sprintf("(index:%d value:%v) ", index, value))
    80  	}
    81  	return b.String()
    82  }
    83  
    84  // UnmarshalJSON @implements json.Unmarshaler
    85  func (queue *Queue[E]) UnmarshalJSON(bytes []byte) error {
    86  	return queue.heap.UnmarshalJSON(bytes)
    87  }
    88  
    89  // MarshalJSON @implements json.Marshaler
    90  func (queue *Queue[E]) MarshalJSON() ([]byte, error) {
    91  	return queue.heap.MarshalJSON()
    92  }