Documentation
¶
Overview ¶
Package collection provides generic data structures for Go.
All data structures in this package use Go generics to work with any type that satisfies the required constraints.
Stack ¶
A LIFO (Last-In-First-Out) data structure:
stack := collection.NewStack[int]() stack.Push(1) stack.Push(2) val, ok := stack.Pop() // val=2, ok=true
Queue ¶
A FIFO (First-In-First-Out) data structure:
queue := collection.NewQueue[string]()
queue.Enqueue("first")
queue.Enqueue("second")
val, ok := queue.Dequeue() // val="first", ok=true
Set ¶
An unordered collection of unique elements:
set := collection.NewSet[int]() set.Add(1, 2, 3) set.Contains(2) // true set.Remove(2)
BST (Binary Search Tree) ¶
An ordered tree structure for efficient search, insert, and delete:
tree := collection.NewBST[int]() tree.Insert(5, 3, 7, 1, 4) tree.Contains(3) // true values := tree.InOrder() // [1, 3, 4, 5, 7]
Thread Safety ¶
The data structures in this package are NOT thread-safe by default. For concurrent access, use sync primitives around Stack, Queue, Set, and BST.
Design Decisions ¶
- Generic: All structures use type parameters - Zero values work: NewXxx() returns ready-to-use structures - Optional returns: Pop/Dequeue return (value, bool) instead of panicking - Immutable iterators: Values() returns copies, not references
Index ¶
- func ToSliceSorted[T cmp.Ordered](s *Set[T]) []T
- type BST
- func (t *BST[T]) Clear()
- func (t *BST[T]) Contains(value T) bool
- func (t *BST[T]) ForEach(fn func(T))
- func (t *BST[T]) Height() int
- func (t *BST[T]) InOrder() []T
- func (t *BST[T]) Insert(values ...T)
- func (t *BST[T]) IsEmpty() bool
- func (t *BST[T]) Len() int
- func (t *BST[T]) LevelOrder() []T
- func (t *BST[T]) Max() (T, bool)
- func (t *BST[T]) Min() (T, bool)
- func (t *BST[T]) PostOrder() []T
- func (t *BST[T]) PreOrder() []T
- func (t *BST[T]) RangeSearch(min, max T) []T
- func (t *BST[T]) Remove(value T) bool
- func (t *BST[T]) Values() []T
- type Queue
- func (q *Queue[T]) Clear()
- func (q *Queue[T]) Dequeue() (T, bool)
- func (q *Queue[T]) DequeueN(n int) []T
- func (q *Queue[T]) Enqueue(item T)
- func (q *Queue[T]) EnqueueAll(items ...T)
- func (q *Queue[T]) IsEmpty() bool
- func (q *Queue[T]) Len() int
- func (q *Queue[T]) Peek() (T, bool)
- func (q *Queue[T]) Values() []T
- type Set
- func (s *Set[T]) Add(items ...T)
- func (s *Set[T]) Clear()
- func (s *Set[T]) Clone() *Set[T]
- func (s *Set[T]) Contains(item T) bool
- func (s *Set[T]) ContainsAll(items ...T) bool
- func (s *Set[T]) ContainsAny(items ...T) bool
- func (s *Set[T]) Difference(other *Set[T]) *Set[T]
- func (s *Set[T]) Equal(other *Set[T]) bool
- func (s *Set[T]) Filter(predicate func(T) bool) *Set[T]
- func (s *Set[T]) ForEach(fn func(T))
- func (s *Set[T]) Intersection(other *Set[T]) *Set[T]
- func (s *Set[T]) IsEmpty() bool
- func (s *Set[T]) IsSubset(other *Set[T]) bool
- func (s *Set[T]) IsSuperset(other *Set[T]) bool
- func (s *Set[T]) Len() int
- func (s *Set[T]) Remove(items ...T)
- func (s *Set[T]) SymmetricDifference(other *Set[T]) *Set[T]
- func (s *Set[T]) Union(other *Set[T]) *Set[T]
- func (s *Set[T]) Values() []T
- type Stack
- func (s *Stack[T]) Clear()
- func (s *Stack[T]) IsEmpty() bool
- func (s *Stack[T]) Len() int
- func (s *Stack[T]) Peek() (T, bool)
- func (s *Stack[T]) Pop() (T, bool)
- func (s *Stack[T]) PopAll() []T
- func (s *Stack[T]) PopN(n int) []T
- func (s *Stack[T]) Push(item T)
- func (s *Stack[T]) PushAll(items ...T)
- func (s *Stack[T]) Values() []T
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ToSliceSorted ¶ added in v1.1.0
ToSliceSorted returns all elements of s as a sorted slice. Unlike Values(), the result is deterministic — suitable for tests and serialization.
This is a package-level function rather than a method because Go does not allow methods to declare stricter type constraints than their receiver (Set[T comparable] cannot add a cmp.Ordered constraint inside a method signature).
Example:
set := NewSetFrom([]int{3, 1, 2})
ToSliceSorted(set) // [1, 2, 3]
Types ¶
type BST ¶
BST is a generic Binary Search Tree. Elements must be ordered (satisfy cmp.Ordered constraint).
func NewBST ¶
NewBST creates a new empty Binary Search Tree.
Example:
tree := NewBST[int]() tree.Insert(5, 3, 7)
func NewBSTFrom ¶
NewBSTFrom creates a BST from a slice.
func (*BST[T]) ForEach ¶
func (t *BST[T]) ForEach(fn func(T))
ForEach calls a function for each value in sorted order.
func (*BST[T]) Height ¶
Height returns the height of the tree. An empty tree has height 0; a single node has height 1.
func (*BST[T]) InOrder ¶
func (t *BST[T]) InOrder() []T
InOrder returns values in sorted order (left, root, right).
Example:
tree.Insert(5, 3, 7, 1, 4) tree.InOrder() // [1, 3, 4, 5, 7]
func (*BST[T]) Insert ¶
func (t *BST[T]) Insert(values ...T)
Insert adds one or more values to the tree. Duplicate values are ignored.
Example:
tree.Insert(5, 3, 7, 1, 4)
func (*BST[T]) LevelOrder ¶
func (t *BST[T]) LevelOrder() []T
LevelOrder returns values level by level (breadth-first).
func (*BST[T]) Max ¶
Max returns the maximum value in the tree. Returns zero value and false if tree is empty.
func (*BST[T]) Min ¶
Min returns the minimum value in the tree. Returns zero value and false if tree is empty.
func (*BST[T]) PostOrder ¶
func (t *BST[T]) PostOrder() []T
PostOrder returns values in post-order (left, right, root).
func (*BST[T]) PreOrder ¶
func (t *BST[T]) PreOrder() []T
PreOrder returns values in pre-order (root, left, right).
func (*BST[T]) RangeSearch ¶ added in v1.1.0
func (t *BST[T]) RangeSearch(min, max T) []T
RangeSearch returns all values in the inclusive range [min, max] in sorted order. Uses the BST structure to prune branches outside the range efficiently (O(k + log n) for k results rather than O(n)). Returns nil if the tree is empty, min > max, or no values fall in the range.
Example:
tree := NewBSTFrom([]int{1, 3, 5, 7, 9})
tree.RangeSearch(3, 7) // [3, 5, 7]
type Queue ¶
type Queue[T any] struct { // contains filtered or unexported fields }
Queue is a generic FIFO (First-In-First-Out) data structure. The zero value is not usable; use NewQueue to create a Queue.
func NewQueue ¶
NewQueue creates a new empty Queue.
Example:
queue := NewQueue[string]()
queue.Enqueue("task1")
func NewQueueWithCapacity ¶
NewQueueWithCapacity creates a Queue with pre-allocated capacity.
func (*Queue[T]) Dequeue ¶
Dequeue removes and returns the front element. Returns false if the queue is empty.
Example:
val, ok := queue.Dequeue()
if !ok {
// queue was empty
}
func (*Queue[T]) DequeueN ¶ added in v1.1.0
DequeueN removes and returns up to n elements from the front of the queue in FIFO order. If n > Len(), all elements are returned. If n <= 0 or the queue is empty, returns nil.
Example:
q := NewQueue[int]() q.EnqueueAll(1, 2, 3, 4, 5) q.DequeueN(3) // [1, 2, 3]; queue now contains [4, 5]
func (*Queue[T]) Enqueue ¶
func (q *Queue[T]) Enqueue(item T)
Enqueue adds an element to the back of the queue.
Example:
queue.Enqueue("task")
func (*Queue[T]) EnqueueAll ¶
func (q *Queue[T]) EnqueueAll(items ...T)
EnqueueAll adds multiple elements to the queue. Elements are added in order.
type Set ¶
type Set[T comparable] struct { // contains filtered or unexported fields }
Set is a generic unordered collection of unique elements. The zero value is not usable; use NewSet to create a Set.
func NewSet ¶
func NewSet[T comparable]() *Set[T]
NewSet creates a new empty Set.
Example:
set := NewSet[int]() set.Add(1, 2, 3)
func NewSetFrom ¶
func NewSetFrom[T comparable](items []T) *Set[T]
NewSetFrom creates a Set from a slice.
Example:
set := NewSetFrom([]int{1, 2, 2, 3}) // {1, 2, 3}
func NewSetWithCapacity ¶
func NewSetWithCapacity[T comparable](capacity int) *Set[T]
NewSetWithCapacity creates a Set with pre-allocated capacity.
func (*Set[T]) Add ¶
func (s *Set[T]) Add(items ...T)
Add adds one or more elements to the set. Elements already in the set are ignored.
Example:
set.Add(1, 2, 3)
func (*Set[T]) ContainsAll ¶
ContainsAll returns true if all elements are in the set.
func (*Set[T]) ContainsAny ¶
ContainsAny returns true if any element is in the set.
func (*Set[T]) Difference ¶
Difference returns a new set containing elements in s but not in other.
Example:
a := NewSetFrom([]int{1, 2, 3})
b := NewSetFrom([]int{2, 3, 4})
c := a.Difference(b) // {1}
func (*Set[T]) ForEach ¶
func (s *Set[T]) ForEach(fn func(T))
ForEach calls a function for each element in the set.
func (*Set[T]) Intersection ¶
Intersection returns a new set containing elements in both sets.
Example:
a := NewSetFrom([]int{1, 2, 3})
b := NewSetFrom([]int{2, 3, 4})
c := a.Intersection(b) // {2, 3}
func (*Set[T]) IsSuperset ¶
IsSuperset returns true if s contains all elements of other.
func (*Set[T]) Remove ¶
func (s *Set[T]) Remove(items ...T)
Remove removes one or more elements from the set. Elements not in the set are ignored.
func (*Set[T]) SymmetricDifference ¶
SymmetricDifference returns elements in either set but not both.
Example:
a := NewSetFrom([]int{1, 2, 3})
b := NewSetFrom([]int{2, 3, 4})
c := a.SymmetricDifference(b) // {1, 4}
type Stack ¶
type Stack[T any] struct { // contains filtered or unexported fields }
Stack is a generic LIFO (Last-In-First-Out) data structure. The zero value is not usable; use NewStack to create a Stack.
func NewStackWithCapacity ¶
NewStackWithCapacity creates a Stack with pre-allocated capacity. Use this when you know the approximate size to reduce allocations.
func (*Stack[T]) Peek ¶
Peek returns the top element without removing it. Returns false if the stack is empty.
func (*Stack[T]) Pop ¶
Pop removes and returns the top element. Returns false if the stack is empty.
Example:
val, ok := stack.Pop()
if !ok {
// stack was empty
}
func (*Stack[T]) PopAll ¶
func (s *Stack[T]) PopAll() []T
PopAll removes and returns all elements from top to bottom. The stack will be empty after this operation.
func (*Stack[T]) PopN ¶ added in v1.1.0
PopN removes and returns up to n elements from the top of the stack in LIFO order. If n > Len(), all elements are returned. If n <= 0 or the stack is empty, returns nil.
Example:
s := NewStack[int]() s.PushAll(1, 2, 3, 4, 5) // top is 5 s.PopN(3) // [5, 4, 3]; stack now contains [1, 2]
func (*Stack[T]) Push ¶
func (s *Stack[T]) Push(item T)
Push adds an element to the top of the stack.
Example:
stack.Push(42)
Source Files