Documentation
¶
Overview ¶
Package stack provides a generic, thread-safe, last-in-first-out (LIFO) stack data structure.
A stack's zero value is ready for use with default settings.
Example:
s := stack.New[int]() s.Push(1) s.Push(2) val, err := s.Pop() // val: 2, err: nil
Example ¶
This example demonstrates the basic usage of a Stack: creating a new stack, pushing elements onto it, and popping them off.
package main
import (
"fmt"
"codeberg.org/WIZARDELF/golot/stack"
)
func main() {
s := stack.New[int]()
s.Push(10)
s.Push(20)
s.Push(30)
fmt.Printf("Stack size: %d\n", s.Size())
val, err := s.Pop()
if err != nil {
fmt.Printf("Error: %v\n", err)
}
fmt.Printf("Popped: %d\n", val)
val, err = s.Pop()
if err != nil {
fmt.Printf("Error: %v\n", err)
}
fmt.Printf("Popped: %d\n", val)
fmt.Printf("Is empty: %t\n", s.IsEmpty())
}
Output: Stack size: 3 Popped: 30 Popped: 20 Is empty: false
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ErrEmpty = errors.New("stack is empty")
ErrEmpty is returned when Pop or Peek is called on an empty stack.
Functions ¶
This section is empty.
Types ¶
type IStack ¶
type IStack[T any] interface { Size() int IsEmpty() bool Peek() (T, error) Push(element T) Pop() (T, error) }
IStack defines the interface for a generic stack.
type Option ¶
Option is a function that configures a Stack. It's used in the New and NewWithCapacity constructors.
func WithShrinkHeuristics ¶
WithShrinkHeuristics returns an Option that configures the stack's automatic memory shrinking behavior.
'ratio' is the threshold (e.g., 0.5 for 50%) of length-to-capacity below which a shrink may occur. It must be between 0.0 and 1.0. If 'ratio' is 0, automatic shrinking is disabled.
'minCapacity' is the minimum capacity the stack must have before shrinking is considered. This helps prevent performance degradation from "thrashing" on small stacks.
type Stack ¶
type Stack[T any] struct { // contains filtered or unexported fields }
Stack is a generic, thread-safe stack implementation. It features automatic shrinking to manage memory usage efficiently. The zero value for a Stack is an empty stack ready to be used with default settings.
func New ¶
New creates and returns a new, empty Stack with default settings. It can be customized with functional options.
Example of creating a stack with a custom shrink policy:
// Disable automatic shrinking s := stack.New[string](stack.WithShrinkHeuristics[string](0, 0))
func NewWithCapacity ¶
NewWithCapacity creates and returns a new, empty Stack with a pre-allocated capacity. It can be customized with functional options. Pre-allocating capacity can improve performance if the number of elements is known beforehand, as it avoids multiple memory reallocations.
Example ¶
This example demonstrates creating a stack with pre-allocated capacity for performance optimization.
package main
import (
"fmt"
"codeberg.org/WIZARDELF/golot/stack"
)
func main() {
// Create a stack with enough capacity for 100 elements.
s := stack.NewWithCapacity[int](100)
// The following push operations will be efficient as they won't require
// memory reallocations.
for i := 0; i < 100; i++ {
s.Push(i)
}
fmt.Printf("Stack size: %d\n", s.Size())
}
Output: Stack size: 100
func (*Stack[T]) Peek ¶
Peek returns the top element of the stack without removing it. It returns ErrEmpty if the stack is empty.
Example ¶
This example demonstrates the Peek method, which returns the top element of the stack without removing it.
package main
import (
"fmt"
"codeberg.org/WIZARDELF/golot/stack"
)
func main() {
s := stack.New[string]()
s.Push("first")
s.Push("second")
top, _ := s.Peek()
fmt.Printf("Top element is: %s\n", top)
fmt.Printf("Stack size is still: %d\n", s.Size())
}
Output: Top element is: second Stack size is still: 2
func (*Stack[T]) Pop ¶
Pop removes and returns the top element of the stack. It returns ErrEmpty if the stack is empty. This method includes an automatic memory shrink strategy to release unused memory.
Source Files