README
¶
stacks 
The stacks package provides a simple LIFO (last-in, first-out) stack implementation in Go.
It supports push, pop, and peek operations, and uses Go 1.18+ generics.
✨ Features
- ✅ Slice-backed stack
- ✅ Peek at top element without removal
- ✅ Supports generic types with Go 1.18+ generics
- ❌ Not thread-safe (no synchronization)
- ❌ No indexed or random access
🧱 Example
package main
import (
"fmt"
"github.com/byExist/stacks"
)
func main() {
s := stacks.New[int]()
stacks.Push(s, 1)
stacks.Push(s, 2)
stacks.Push(s, 3)
v, ok := stacks.Peek(s)
if ok {
fmt.Println("Peek:", v)
}
for {
v, ok := stacks.Pop(s)
if !ok {
break
}
fmt.Println("Pop:", v)
}
fmt.Println("Length:", stacks.Len(s))
}
// Output:
// Peek: 3
// Pop: 3
// Pop: 2
// Pop: 1
// Length: 0
📚 Use When
- You want to manage data in LIFO order
- You need a minimal in-memory stack using Go generics
- You need a reusable stack for short-lived values
🚫 Avoid If
- You need thread-safe access from multiple goroutines
- You require random or indexed access to elements
- You need allocation guarantees under heavy load
🔍 API
Functions
| Function | Description |
|---|---|
New[T]() |
Create a new empty stack |
Collect[T](seq iter.Seq[T]) |
Build a stack from an iterator |
Push(s *Stack[T], item T) |
Push an item onto the stack |
Pop(s *Stack[T]) (T, bool) |
Pop the top item from the stack |
Peek(s *Stack[T]) (T, bool) |
Peek at the top item without removing it |
Clear(s *Stack[T]) |
Remove all items |
Clone(s *Stack[T]) *Stack[T] |
Create a shallow copy |
Len(s *Stack[T]) int |
Return number of items in the stack |
Values(s *Stack[T]) iter.Seq[T] |
Return an iterator for the stack |
Methods
| Method | Description |
|---|---|
(*Stack[T]) String() string |
Return a string representation |
(*Stack[T]) MarshalJSON() ([]byte, error) |
Serialize the stack to JSON |
(*Stack[T]) UnmarshalJSON([]byte) error |
Deserialize JSON into the stack |
🪪 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/stacks"
)
func main() {
s := stacks.New[int]()
stacks.Push(s, 123)
stacks.Push(s, 456)
fmt.Println("Before clear:", stacks.Len(s))
stacks.Clear(s)
fmt.Println("After clear:", stacks.Len(s))
}
Output: Before clear: 2 After clear: 0
func Len ¶
Len returns the number of elements in the stack.
Example ¶
package main
import (
"fmt"
"github.com/byExist/stacks"
)
func main() {
s := stacks.New[int]()
fmt.Println(stacks.Len(s))
stacks.Push(s, 1)
stacks.Push(s, 2)
fmt.Println(stacks.Len(s))
_, _ = stacks.Pop(s)
fmt.Println(stacks.Len(s))
}
Output: 0 2 1
func Peek ¶
Peek returns the top element without removing it. Returns false if the stack is empty.
Example ¶
package main
import (
"fmt"
"github.com/byExist/stacks"
)
func main() {
s := stacks.New[int]()
stacks.Push(s, 42)
val, ok := stacks.Peek(s)
if ok {
fmt.Println(val)
}
}
Output: 42
func Pop ¶
Pop removes and returns the top element of the stack. Returns false if the stack is empty.
Example ¶
package main
import (
"fmt"
"github.com/byExist/stacks"
)
func main() {
s := stacks.New[int]()
stacks.Push(s, 1)
stacks.Push(s, 2)
val, ok := stacks.Pop(s)
if ok {
fmt.Println(val)
}
}
Output: 2
func Push ¶
Push adds an element to the top of the stack.
Example ¶
package main
import (
"fmt"
"github.com/byExist/stacks"
)
func main() {
s := stacks.New[string]()
stacks.Push(s, "alpha")
stacks.Push(s, "beta")
for v := range stacks.Values(s) {
fmt.Println(v)
}
}
Output: alpha beta
func Values ¶
Values returns a sequence that yields all elements in the stack from bottom to top.
Example ¶
package main
import (
"fmt"
"github.com/byExist/stacks"
)
func main() {
s := stacks.New[int]()
stacks.Push(s, 5)
stacks.Push(s, 10)
for v := range stacks.Values(s) {
fmt.Println(v)
}
}
Output: 5 10
Types ¶
type Stack ¶
type Stack[T any] struct { // contains filtered or unexported fields }
Stack is a generic, dynamically resizing stack.
func Clone ¶
Clone creates a shallow copy of the stack.
Example ¶
package main
import (
"fmt"
"github.com/byExist/stacks"
)
func main() {
s := stacks.New[string]()
stacks.Push(s, "x")
stacks.Push(s, "y")
clone := stacks.Clone(s)
stacks.Push(s, "z") // Modify original
for v := range stacks.Values(clone) {
fmt.Println(v)
}
}
Output: x y
func Collect ¶
Collect builds a stack from a given sequence of elements.
Example ¶
package main
import (
"fmt"
"slices"
"github.com/byExist/stacks"
)
func main() {
seq := slices.Values([]int{10, 20, 30})
s := stacks.Collect(seq)
for v := range stacks.Values(s) {
fmt.Println(v)
}
}
Output: 10 20 30
func New ¶
New creates a new empty stack.
Example ¶
package main
import (
"fmt"
"github.com/byExist/stacks"
)
func main() {
s := stacks.New[int]()
stacks.Push(s, 1)
stacks.Push(s, 2)
for v := range stacks.Values(s) {
fmt.Println(v)
}
}
Output: 1 2
func (*Stack[T]) MarshalJSON ¶ added in v0.1.0
MarshalJSON implements json.Marshaler for Stack.
Example ¶
package main
import (
"encoding/json"
"fmt"
"github.com/byExist/stacks"
)
func main() {
s := stacks.New[int]()
stacks.Push(s, 1)
stacks.Push(s, 2)
b, _ := json.Marshal(s)
fmt.Println(string(b))
}
Output: [1,2]
func (*Stack[T]) String ¶ added in v0.1.0
String returns a string representation of the stack.
Example ¶
package main
import (
"fmt"
"github.com/byExist/stacks"
)
func main() {
s := stacks.New[int]()
stacks.Push(s, 1)
stacks.Push(s, 2)
fmt.Println(s)
}
Output: Stack{1, 2}
func (*Stack[T]) UnmarshalJSON ¶ added in v0.1.0
UnmarshalJSON implements json.Unmarshaler for Stack.
Example ¶
package main
import (
"encoding/json"
"fmt"
"github.com/byExist/stacks"
)
func main() {
var s stacks.Stack[int]
_ = json.Unmarshal([]byte(`[5,10]`), &s)
for v := range stacks.Values(&s) {
fmt.Println(v)
}
}
Output: 5 10
Source Files
Click to show internal directories.
Click to hide internal directories.