README
¶
queues 
A simple, allocation-efficient FIFO queue implementation in Go.
The queues package provides a dynamically resizing, ring-buffer queue supporting enqueue, dequeue, and peek operations. It is a simple, allocation-efficient queue designed for streaming or producer-consumer scenarios.
✨ Features
- ✅ Dynamically resizing ring buffer queue
- ✅ Efficient enqueue and dequeue operations
- ✅ Peek at front element without removal
- ✅ Supports generic types with Go 1.18+ generics
- ❌ Not thread-safe (no synchronization)
- ❌ No priority or indexed access
🧱 Example
package main
import (
"fmt"
"github.com/byExist/queues"
)
func main() {
q := queues.New[int]()
queues.Enqueue(q, 10)
queues.Enqueue(q, 20)
queues.Enqueue(q, 30)
for v := range queues.Values(q) {
fmt.Println(v)
}
}
📚 Use When
- You need FIFO data structure
- You want allocation-efficient buffered queues
- You process items in a streaming or producer-consumer model
🚫 Avoid If
- You need concurrent access (not thread-safe)
- You want priority-based scheduling or indexed random access
🔍 API
| Function | Description |
|---|---|
New[T]() |
Create a new empty queue |
NewWithCapacity[T](capacity int) |
Create a new queue with initial capacity |
Collect(seq) |
Build a queue from an iterator |
Clone() |
Return a shallow copy of the queue |
Clear() |
Remove all elements from the queue |
Enqueue(q *Queue[T], item T) |
Add item to the back of the queue |
Dequeue(q *Queue[T]) (T, bool) |
Remove and return front item |
Peek(q *Queue[T]) (T, bool) |
Return front item without removal |
Len() int |
Number of elements in queue |
Values() |
Iterate over queue elements |
Methods
| Method | Description |
|---|---|
q.String() |
Returns a string representation |
q.MarshalJSON() / q.UnmarshalJSON() |
JSON serialization support |
🪪 License
MIT License. See LICENSE.
Documentation
¶
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Clear ¶
Clear removes all elements but keeps the allocated capacity.
Example ¶
package main
import (
"fmt"
"github.com/byExist/queues"
)
func main() {
q := queues.New[int]()
queues.Enqueue(q, 1)
queues.Clear(q)
fmt.Println(queues.Len(q))
}
Output: 0
func Dequeue ¶
Dequeue removes and returns the front element of the queue. Returns false if the queue is empty.
Example ¶
package main
import (
"fmt"
"github.com/byExist/queues"
)
func main() {
q := queues.New[int]()
queues.Enqueue(q, 7)
v, _ := queues.Dequeue(q)
fmt.Println(v)
}
Output: 7
func Enqueue ¶
Enqueue adds an element to the end of the queue.
Example ¶
package main
import (
"fmt"
"github.com/byExist/queues"
)
func main() {
q := queues.New[int]()
queues.Enqueue(q, 5)
v, _ := queues.Peek(q)
fmt.Println(v)
}
Output: 5
func Len ¶
Len returns the number of elements in the queue.
Example ¶
package main
import (
"fmt"
"github.com/byExist/queues"
)
func main() {
q := queues.New[int]()
fmt.Println(queues.Len(q))
queues.Enqueue(q, 1)
fmt.Println(queues.Len(q))
}
Output: 0 1
func Peek ¶
Peek returns the front element without removing it. Returns false if the queue is empty.
Example ¶
package main
import (
"fmt"
"github.com/byExist/queues"
)
func main() {
q := queues.New[int]()
queues.Enqueue(q, 99)
v, _ := queues.Peek(q)
fmt.Println(v)
}
Output: 99
Types ¶
type Queue ¶
type Queue[T any] struct { // contains filtered or unexported fields }
Queue is a generic, dynamically resizing circular queue.
func Clone ¶ added in v0.0.3
Clone creates a new queue with the same elements as the given queue.
Example ¶
package main
import (
"fmt"
"github.com/byExist/queues"
)
func main() {
q := queues.New[int]()
queues.Enqueue(q, 1)
queues.Enqueue(q, 2)
copied := queues.Clone(q)
for v := range queues.Values(copied) {
fmt.Print(v)
}
}
Output: 12
func Collect ¶
Collect builds a queue from a given sequence of elements.
Example ¶
package main
import (
"fmt"
"slices"
"github.com/byExist/queues"
)
func main() {
seq := slices.Values([]int{1, 2, 3})
q := queues.Collect(seq)
for v := range queues.Values(q) {
fmt.Print(v)
}
}
Output: 123
func New ¶
New creates a new empty queue.
Example ¶
package main
import (
"fmt"
"github.com/byExist/queues"
)
func main() {
q := queues.New[int]()
queues.Enqueue(q, 10)
v, _ := queues.Dequeue(q)
fmt.Println(v)
}
Output: 10
func NewWithCapacity ¶
NewWithCapacity creates a new queue with a specified initial capacity.
Example ¶
package main
import (
"fmt"
"github.com/byExist/queues"
)
func main() {
q := queues.NewWithCapacity[int](5)
for i := 1; i <= 5; i++ {
queues.Enqueue(q, i)
}
for v := range queues.Values(q) {
fmt.Print(v)
}
}
Output: 12345
func (*Queue[T]) MarshalJSON ¶ added in v0.1.0
MarshalJSON implements json.Marshaler for Queue.
Example ¶
package main
import (
"encoding/json"
"fmt"
"github.com/byExist/queues"
)
func main() {
q := queues.New[int]()
queues.Enqueue(q, 5)
queues.Enqueue(q, 15)
data, _ := json.Marshal(q)
fmt.Println(string(data))
}
Output: [5,15]
func (*Queue[T]) String ¶ added in v0.1.0
String returns a string representation of the queue.
Example ¶
package main
import (
"fmt"
"github.com/byExist/queues"
)
func main() {
q := queues.New[int]()
queues.Enqueue(q, 10)
queues.Enqueue(q, 20)
fmt.Println(q.String())
}
Output: Queue{10, 20}
func (*Queue[T]) UnmarshalJSON ¶ added in v0.1.0
UnmarshalJSON implements json.Unmarshaler for Queue.
Example ¶
package main
import (
"encoding/json"
"fmt"
"github.com/byExist/queues"
)
func main() {
var q queues.Queue[int]
_ = json.Unmarshal([]byte(`[3,6,9]`), &q)
for v := range queues.Values(&q) {
fmt.Print(v)
}
}
Output: 369
Source Files