gds — Generic Data Structures for Go

A collection of generic, zero-dependency data structures for Go 1.21+. All structures are not safe for concurrent use unless stated otherwise.

---

Install

go get github.com/renaldid/gds

---

Structures

Type	Description
Set[T]	Unordered unique elements
SortedSet[T]	Sorted unique elements with binary search
OrderedMap[K,V]	Map that preserves insertion order
MultiMap[K,V]	Map with multiple values per key
Stack[T]	LIFO stack
Queue[T]	FIFO queue with auto-compaction
Deque[T]	Double-ended queue, O(1) amortized
PriorityQueue[T]	Binary heap with custom comparator
RingBuffer[T]	Fixed-capacity circular buffer
LinkedList[T]	Doubly-linked list with node handles

---

Set

s := gds.NewSet(1, 2, 3)
s.Add(4)
s.Remove(2)
s.Contains(3)   // true

a := gds.NewSet(1, 2, 3)
b := gds.NewSet(2, 3, 4)
a.Union(b)        // {1,2,3,4}
a.Intersection(b) // {2,3}
a.Difference(b)   // {1}

SortedSet

s := gds.NewSortedSet(3, 1, 4, 1, 5)
s.Items()       // [1 3 4 5]  (sorted, deduped)
s.Min()         // 1, true
s.Max()         // 5, true
s.Contains(4)   // true

s.Range(func(v int) bool {
    fmt.Println(v)
    return true // return false to stop early
})

OrderedMap

m := gds.NewOrderedMap[string, int]()
m.Set("b", 2)
m.Set("a", 1)
m.Set("c", 3)
m.Keys()   // ["b", "a", "c"]  (insertion order)
m.Delete("a")

m.Range(func(k string, v int) bool {
    fmt.Printf("%s=%d\n", k, v)
    return true
})

MultiMap

mm := gds.NewMultiMap[string, string]()
mm.Add("fruits", "apple", "banana")
mm.Add("fruits", "cherry")
mm.Get("fruits")     // ["apple", "banana", "cherry"], true
mm.TotalValues()     // 3

gds.MultiMapRemoveValue(mm, "fruits", "banana")

Stack

s := gds.NewStack[int]()
s.Push(1, 2, 3)
s.Pop()    // 3, true
s.Peek()   // 2, true

Queue

q := gds.NewQueue[string]()
q.Enqueue("a", "b", "c")
q.Dequeue()   // "a", true
q.Peek()      // "b", true

Deque

d := gds.NewDeque[int]()
d.PushBack(1, 2, 3)
d.PushFront(0)
d.PopFront()   // 0, true
d.PopBack()    // 3, true

PriorityQueue

// min-heap
pq := gds.NewPriorityQueue(func(a, b int) bool { return a < b })
pq.Push(5, 1, 3)
pq.Pop()    // 1, true
pq.Peek()   // 3, true

// custom type
type Task struct{ Name string; Priority int }
pq := gds.NewPriorityQueue(func(a, b Task) bool {
    return a.Priority < b.Priority
})

RingBuffer

r := gds.NewRingBuffer[int](4)
r.Push(1)   // true
r.Push(2)   // true
r.IsFull()  // false
r.Pop()     // 1, true
r.Cap()     // 4

LinkedList

l := gds.NewLinkedList[int]()
a := l.PushBack(1)
b := l.PushBack(3)
l.InsertAfter(2, a)    // insert 2 after a → [1,2,3]
l.InsertBefore(0, a)   // insert 0 before a → [0,1,2,3]
l.Remove(b)            // removes node b

// traverse
for n := l.Front(); n != nil; n = n.Next() {
    fmt.Println(n.Value)
}

---

License

MIT — see LICENSE.