README
¶
collections-go
A library/package of common generic collection data structures in Go
Documentation
¶
Index ¶
- Variables
- type Deque
- func (q *Deque[T]) AsSlice() []T
- func (q *Deque[T]) Back() (T, bool)
- func (q *Deque[T]) Capacity() int
- func (q *Deque[T]) Clear()
- func (q *Deque[T]) Front() (T, bool)
- func (q *Deque[T]) GetAt(idx int) T
- func (q *Deque[T]) IsEmpty() bool
- func (q *Deque[T]) Len() int
- func (q *Deque[T]) PopBack() (T, bool)
- func (q *Deque[T]) PopFront() (T, bool)
- func (q *Deque[T]) PushBack(elem T)
- func (q *Deque[T]) PushFront(elem T)
- type OrderedMap
- func (m *OrderedMap[K, V]) Contains(key K) bool
- func (m *OrderedMap[K, V]) Delete(key K) bool
- func (m *OrderedMap[K, V]) ForEach(fn func(key K, val V))
- func (m *OrderedMap[K, V]) ForEachReverse(fn func(key K, val V))
- func (m *OrderedMap[K, V]) Get(key K) (V, bool)
- func (m *OrderedMap[K, V]) GetOrDefault(key K, defaultValue V) V
- func (m *OrderedMap[K, V]) Keys() []K
- func (m *OrderedMap[K, V]) Set(key K, val V) bool
- func (m *OrderedMap[K, V]) Size() int
- type PriorityQueue
- type Queue
- type Set
- func (s *Set[T]) Add(vals ...T)
- func (s *Set[T]) AsSlice() []T
- func (s *Set[T]) Clone() *Set[T]
- func (s *Set[T]) Contains(val T) bool
- func (s *Set[T]) Difference(other *Set[T]) *Set[T]
- func (s *Set[T]) Equals(other *Set[T]) bool
- func (s *Set[T]) ForEach(fn func(val T))
- func (s *Set[T]) Iter() *SetIterator[T]
- func (s *Set[T]) MarshalJSON() ([]byte, error)
- func (s *Set[T]) MarshalMsgpack() ([]byte, error)
- func (s *Set[T]) Remove(val T)
- func (s *Set[T]) Size() int
- func (s *Set[T]) Union(other *Set[T]) *Set[T]
- func (s *Set[T]) UnmarshalJSON(data []byte) error
- func (s *Set[T]) UnmarshalMsgpack(data []byte) error
- type SetIterator
- type Stack
Constants ¶
This section is empty.
Variables ¶
var ( // ErrEmptyStack is a sentinel error value indicating the operation cannot // be performed on an empty stack. ErrEmptyStack = errors.New("stack is empty") )
Functions ¶
This section is empty.
Types ¶
type Deque ¶
type Deque[T any] struct { // contains filtered or unexported fields }
Deque is a linear collection of elements that supports insertion and deletion at both ends. Deque is short for double ended queue.
Deque efficiently handles adding and removing elements at either end with O(1) performance. This is accomplished using a ring buffer to store the data which reduces pressure on garbage collector and more efficiently uses memory when compared to implementations that use linked lists or slices.
Deque can be used as both a queue or a stack.
Stack PushBack - Push element to top of stack PopBack - Pop top element off the stack Back - Peek at the top of the stack Queue PushBack- Add element to end of the queue PopFront - Poll the first element at the head of the queue Front - Peek at the next element in the queue
This package also provides Queue and Stack types which wraps Deque in a simpler API.
The zero-value of Deque is not usable. New instances of Deque should be created and initialized using NewDeque function.
func (*Deque[T]) AsSlice ¶
func (q *Deque[T]) AsSlice() []T
AsSlice returns an array containing all the elements of the Deque in order of front/head to back/tail.
func (*Deque[T]) Back ¶
Back returns the last element of the Deque. If the Deque is empty the zero-value will be returned with a bool value of false.
func (*Deque[T]) Capacity ¶
Capacity returns the size of the underlying ring-buffer holding the elements.
func (*Deque[T]) Clear ¶
func (q *Deque[T]) Clear()
Clear removes all the elements from the Deque but retains the current capacity.
func (*Deque[T]) Front ¶
Front returns the first element of the Deque. If the Deque is empty the zero-value will be returned with a bool value of false.
func (*Deque[T]) GetAt ¶
GetAt returns the element at the provided index.
If the index is not valid this will panic.
func (*Deque[T]) PopBack ¶
PopBack pops the back/last element of the Deque removing it and returning the value. If the Deque is empty the zero-value will be returned with a bool value of false.
func (*Deque[T]) PopFront ¶
PopFront pops the front/first element of the Deque removing it and returning the value. If the Deque is empty the zero-value will be returned with a bool value of false.
type OrderedMap ¶
type OrderedMap[K comparable, V any] struct { // contains filtered or unexported fields }
OrderedMap is a map implementation that maintains the order keys were inserted into the map. Set, Get, and Delete operations remain O(1) and the keys can be iterated in the order they were added using ForEach, or in reverse order using ForEachReverse.
The zero-value of OrderedMap is not usable. NewOrderedMap should be used to create and initialize a new instance of OrderedMap.
func NewOrderedMap ¶
func NewOrderedMap[K comparable, V any]() *OrderedMap[K, V]
NewOrderedMap creates and initializes a new OrderedMap
func (*OrderedMap[K, V]) Contains ¶
func (m *OrderedMap[K, V]) Contains(key K) bool
Contains returns true if the given key exists in the OrderedMap, otherwise returns false.
func (*OrderedMap[K, V]) Delete ¶
func (m *OrderedMap[K, V]) Delete(key K) bool
Delete removes a key/value entry from the OrderedMap. If the key didn't exist returns false so, otherwise returns true if the entry was deleted.
func (*OrderedMap[K, V]) ForEach ¶
func (m *OrderedMap[K, V]) ForEach(fn func(key K, val V))
ForEach iterates through the map entries passing the key/value pair to the provided function/closure in the order they were inserted.
func (*OrderedMap[K, V]) ForEachReverse ¶
func (m *OrderedMap[K, V]) ForEachReverse(fn func(key K, val V))
ForEachReverse iterates through the map entries passing the key/value pairs to the provided function/closure in the reverse order they were inserted (most recently inserted to least recently)
func (*OrderedMap[K, V]) Get ¶
func (m *OrderedMap[K, V]) Get(key K) (V, bool)
Get retrieves the value for a key. It follows the same idioms of the built-in map. If the key doesn't exist the zero value and false value are returned.
func (*OrderedMap[K, V]) GetOrDefault ¶
func (m *OrderedMap[K, V]) GetOrDefault(key K, defaultValue V) V
GetOrDefault retrieves the value for a key and if it doesn't exist returns the provided default value.
func (*OrderedMap[K, V]) Keys ¶
func (m *OrderedMap[K, V]) Keys() []K
Keys returns the keys in the order they were inserted.
func (*OrderedMap[K, V]) Set ¶
func (m *OrderedMap[K, V]) Set(key K, val V) bool
Set inserts a new key/value into the map or replaces the value for an existing key. If the key didn't exist in the map and was inserted true is returned. Otherwise, if they key was already existing returns false.
func (*OrderedMap[K, V]) Size ¶
func (m *OrderedMap[K, V]) Size() int
Size returns the number of entries in the OrderedMap
type PriorityQueue ¶ added in v0.2.0
type PriorityQueue[T any] struct { // contains filtered or unexported fields }
PriorityQueue is a queue data structure that orders elements according to priority. When Pop is invoked the item with the highest priority is returned.
The zero-value of PriorityQueue is not usable. Use NewPriorityQueue to create and initialize a new PriorityQueue.
func NewPriorityQueue ¶ added in v0.2.0
func NewPriorityQueue[T any]() *PriorityQueue[T]
NewPriorityQueue creates and initializes a new PriorityQueue.
func (*PriorityQueue[T]) IsEmpty ¶ added in v0.2.0
func (pq *PriorityQueue[T]) IsEmpty() bool
IsEmpty returns true if the PriorityQueue is empty, otherwise false.
func (*PriorityQueue[T]) Len ¶ added in v0.2.0
func (pq *PriorityQueue[T]) Len() int
Len returns the length/size of the PriorityQueue.
func (*PriorityQueue[T]) Peek ¶ added in v0.2.0
func (pq *PriorityQueue[T]) Peek() (T, bool)
Peek returns the next element to be polled from the PriorityQueue. If the queue is empty the zero value is returned with a boolean value of false.
func (*PriorityQueue[T]) Poll ¶ added in v0.2.0
func (pq *PriorityQueue[T]) Poll() (T, bool)
Poll retrieves the highest priority item from the queue and removes it from the PriorityQueue. If the queue is empty the zero value is returned with a boolean value of false.
func (*PriorityQueue[T]) Push ¶ added in v0.2.0
func (pq *PriorityQueue[T]) Push(val T, priority int)
Push adds an element to the PriorityQueue with the specified priority.
type Queue ¶
type Queue[T any] struct { // contains filtered or unexported fields }
Queue represents an unbounded first-in-first-out queue of elements.
Under the hood Queue simply wraps Deque to provide a more friendly API for working with queues.
The zero-value of Queue is not usable. Queue should be created/initialized using NewQueue.
func (*Queue[T]) Empty ¶
Empty returns a boolean value indicating if the Queue is empty, true if it is empty, otherwise false.
func (*Queue[T]) Offer ¶
func (q *Queue[T]) Offer(val T)
Offer inserts/adds an element at the end of the queue.
func (*Queue[T]) Peek ¶
Peek retrieves and returns the first element in the queue. Unlike Poll, the element is not removed. If the queue is empty the zero value will be returned along with an ok value of false.
type Set ¶
type Set[T comparable] struct { // contains filtered or unexported fields }
Set is a collection that contains no duplicate elements. More formally, sets contain no pair of elements e1 and e2 such that e1 == e2. As implied by its name, Set models the mathematical set abstraction.
Set makes no guarantees as to the iteration order of the set; in particular, it does not guarantee that the order will remain constant over time.
The zero-value of Set is not usable. Set should be created and initialized using NewSet function.
Set supports marshaling/unmarshalling for json and msgpack out of the box.
Note: Set is not thread safe.
func (*Set[T]) Add ¶
func (s *Set[T]) Add(vals ...T)
Add adds the elements into the Set. If an element already exists it is effectively a no-op.
func (*Set[T]) AsSlice ¶
func (s *Set[T]) AsSlice() []T
AsSlice converts a Set to a built-in Go slice.
func (*Set[T]) Contains ¶
Contains reads through the Set and returns a boolean value indicating if the provided value is in the Set.
func (*Set[T]) Difference ¶
Difference returns a new Set containing all the elements in other that did not exists in current Set.
func (*Set[T]) Equals ¶
Equals returns a boolean indicating if the Set is equal to the provided Set.
func (*Set[T]) ForEach ¶
func (s *Set[T]) ForEach(fn func(val T))
ForEach iterates through the Set passing the value to the provided function.
func (*Set[T]) Iter ¶
func (s *Set[T]) Iter() *SetIterator[T]
Iter returns a stateful iterator for iterator over a Set.
Note: Internally AsSlice is called to populate the SetIterator. In the vast majority of use cases this is unlikely to matter. However, if the Set contains a vast amount of data it may be more efficient to use ForEach with a closure.
func (*Set[T]) MarshalJSON ¶
MarshalJSON marshals a Set into binary JSON representation
func (*Set[T]) MarshalMsgpack ¶
MarshalMsgpack marshals a Set into binary msgpack representation.
func (*Set[T]) Remove ¶
func (s *Set[T]) Remove(val T)
Remove removes/deletes an element from the Set. If the element doesn't exist this is a no-op.
func (*Set[T]) UnmarshalJSON ¶
UnmarshalJSON unmarshalls binary JSON representation of a Set into this instance of Set.
func (*Set[T]) UnmarshalMsgpack ¶
UnmarshalMsgpack unmarshalls binary msgpack representation of a Set into this instance of Set.
type SetIterator ¶
type SetIterator[T comparable] struct { // contains filtered or unexported fields }
SetIterator is a stateful iterator for iterating through a Set.
func (*SetIterator[T]) Next ¶
func (s *SetIterator[T]) Next() bool
Next moves the iterator to the next element/value and returns a boolean indicating if there is a valid value.
type Stack ¶
type Stack[T any] struct { // contains filtered or unexported fields }
Stack represents a last-in-first-out (LIFO) stack of elements.
Under the hood Stack simply wraps Deque to provide a more friendly API for working with stacks.
The zero-value of Stack is not usable. In order to properly initialize and use Stack use the NewStack function.
func (*Stack[T]) Peek ¶
Peek returns the element at the top of the stack but doesn't remove it. Peek additionally returns a boolean indicating if a value was returned. If the stack was empty false we be returned.
func (*Stack[T]) Pop ¶
Pop removes and returns the element at the top of the stack. In the event the Stack is empty a non-nil error value of ErrEmptyStack is returned.
func (*Stack[T]) PopEach ¶
func (s *Stack[T]) PopEach(fn func(val T))
PopEach will pop each element off the stack one by one until the stack is empty. As each element is popped off the stack the provided function is executed with the popped off value.
Source Files
Directories