gocircular

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Dec 6, 2025 License: MIT Imports: 1 Imported by: 1

README

gocircular

A fast, generic circular buffer (ring buffer) implementation for Go 1.23+.

Features

  • Generics: Type-safe buffer for any type
  • O(1) operations: Push/pop at both ends
  • Iterator support: Go 1.23 iter.Seq and iter.Seq2 iterators
  • Auto-overwrite: When full, new elements overwrite oldest ones
  • Zero dependencies: Standard library only

Installation

go get github.com/rvncerr/gocircular

Usage

package main

import (
    "fmt"
    "github.com/rvncerr/gocircular"
)

func main() {
    // Create a buffer with capacity 3
    buf := gocircular.New[int](3)

    // Add elements
    buf.PushBack(1)
    buf.PushBack(2)
    buf.PushBack(3)
    buf.PushBack(4) // Overwrites 1

    // Access elements
    front, _ := buf.Front() // 2
    back, _ := buf.Back()   // 4
    
    // Iterate using Go 1.23 iterators
    for i, v := range buf.All() {
        fmt.Printf("buf[%d] = %d\n", i, v)
    }
    
    // Convert to slice
    slice := buf.ToSlice() // [2, 3, 4]
}

API Reference

Creation
Function Description
New[T](capacity) Create a new buffer with given capacity
Push/Pop Operations
Method Description
PushBack(value) Add to back, returns true if element was overwritten
PushFront(value) Add to front, returns true if element was overwritten
PopBack() Remove and return back element
PopFront() Remove and return front element
Access Operations
Method Description
Front() Return front element without removing
Back() Return back element without removing
At(index) Return element at index (0-based from front)
Set(index, value) Update element at index
State Operations
Method Description
Len() Number of elements
Cap() Buffer capacity
Empty() True if buffer has no elements
Full() True if buffer is at capacity
Clear() Remove all elements
Iteration
Method Description
All() Iterator yielding (index, value) pairs front-to-back
Values() Iterator yielding values front-to-back
Backward() Iterator yielding (index, value) pairs back-to-front
Do(func(T) bool) Call function on each element, stop if returns false
Conversion & Manipulation
Method Description
ToSlice() Return elements as a slice
Clone() Create a deep copy
Resize(newCap) Change capacity (discards back elements if shrinking)

License

MIT License - see LICENSE file.

Documentation

Overview

Package gocircular provides a generic circular buffer implementation.

A circular buffer (also known as a ring buffer) is a fixed-size data structure that uses a single, continuous buffer as if it were connected end-to-end. When the buffer is full, new elements overwrite the oldest elements.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Buffer

type Buffer[T any] struct {
	// contains filtered or unexported fields
}

Buffer is a generic circular buffer with a fixed capacity. It supports efficient O(1) operations at both ends.

func New

func New[T any](capacity int) *Buffer[T]

New creates a new circular buffer with the given capacity. Panics if capacity is less than 1.

func (*Buffer[T]) All

func (b *Buffer[T]) All() iter.Seq2[int, T]

All returns an iterator over all elements from front to back. The iterator yields index and value pairs.

func (*Buffer[T]) At

func (b *Buffer[T]) At(i int) (T, bool)

At returns the element at the given index (0-based from front). Returns the zero value and false if the index is out of bounds.

func (*Buffer[T]) Back

func (b *Buffer[T]) Back() (T, bool)

Back returns the back element without removing it. Returns the zero value and false if the buffer is empty.

func (*Buffer[T]) Backward

func (b *Buffer[T]) Backward() iter.Seq2[int, T]

Backward returns an iterator over all elements from back to front. The iterator yields index and value pairs (indices are still front-based).

func (*Buffer[T]) Cap

func (b *Buffer[T]) Cap() int

Cap returns the capacity of the buffer.

func (*Buffer[T]) Clear

func (b *Buffer[T]) Clear()

Clear removes all elements from the buffer.

func (*Buffer[T]) Clone

func (b *Buffer[T]) Clone() *Buffer[T]

Clone creates a deep copy of the buffer.

func (*Buffer[T]) Do

func (b *Buffer[T]) Do(f func(T) bool)

Do calls the function f on each element from front to back. If f returns false, iteration stops early.

func (*Buffer[T]) Empty

func (b *Buffer[T]) Empty() bool

Empty returns true if the buffer has no elements.

func (*Buffer[T]) Front

func (b *Buffer[T]) Front() (T, bool)

Front returns the front element without removing it. Returns the zero value and false if the buffer is empty.

func (*Buffer[T]) Full

func (b *Buffer[T]) Full() bool

Full returns true if the buffer is at capacity.

func (*Buffer[T]) Len

func (b *Buffer[T]) Len() int

Len returns the number of elements in the buffer.

func (*Buffer[T]) PopBack

func (b *Buffer[T]) PopBack() (T, bool)

PopBack removes and returns the back element. Returns the zero value and false if the buffer is empty.

func (*Buffer[T]) PopFront

func (b *Buffer[T]) PopFront() (T, bool)

PopFront removes and returns the front element. Returns the zero value and false if the buffer is empty.

func (*Buffer[T]) PushBack

func (b *Buffer[T]) PushBack(v T) bool

PushBack adds an element to the back of the buffer. If the buffer is full, the front element is overwritten. Returns true if an element was overwritten.

func (*Buffer[T]) PushFront

func (b *Buffer[T]) PushFront(v T) bool

PushFront adds an element to the front of the buffer. If the buffer is full, the back element is overwritten. Returns true if an element was overwritten.

func (*Buffer[T]) Resize

func (b *Buffer[T]) Resize(n int)

Resize changes the buffer capacity. If shrinking, elements at the back are discarded to fit the new capacity. Panics if n is less than 1.

func (*Buffer[T]) Set

func (b *Buffer[T]) Set(i int, v T) bool

Set updates the element at the given index (0-based from front). Returns false if the index is out of bounds.

func (*Buffer[T]) ToSlice

func (b *Buffer[T]) ToSlice() []T

ToSlice returns a new slice containing all elements in order (front to back).

func (*Buffer[T]) Values

func (b *Buffer[T]) Values() iter.Seq[T]

Values returns an iterator over all values from front to back.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL