ringbuffer

README

Ring Buffer (circular buffer)

A ring buffer is a fixed-size container as a data structure.

A lot of ring buffer implementations do not allow overwrites when the buffer is full... but I wanted that functionality, so I made this. If someone desires the ability to default deny overwrites, please make a pull request!

Please note: Even though this implementation allows overwrites, it will NOT allow writing more data than the total size of the buffer.

In other words - a single write must be equal or less than the total size of the ring buffer.

Example usage

First, get the package:

go get github.com/euheimr/ringbuffer

Example usage:

package main

import (
	"fmt"
	"github.com/euheimr/ringbuffer"
)

func main() {
   capacity := 3
   // Create a new ring buffer of type `string` and fixed `capacity` or size. The capacity
   //  defines how many elements are in the buffer. 
   // Please note that the buffer itself is zero-indexed. In other words, with a capacity
   //  of 3, the last index of the buffer is 2, and the first element is 0.
   rb, err := ringbuffer.New[string](capacity)
   if err != nil {
      fmt.Println(err.Error())
   }

   // Write a single value
   rb.Write("test1")
   fmt.Println(rb.Read())   // rb.Read() == []string{"test1"}

   // Write multiple values
   if err = rb.WriteMany([]string{"test2", "test3", "test4"}); err != nil {
      fmt.Println(err.Error())
   }

   // Read the buffer in order of FIFO (first-in-first-out)
   fmt.Println(rb.Read())  // rb.Read() == []string{"test2", "test3", "test4"}
   
   // You can recreate the buffer with a new size! However, it MUST be EQUAL or GREATER 
   // than the number of EXISTING elements. 
   // If you want to make it smaller than the existing buffer, you must call rb.Reset() 
   // to clear the buffer data, then rb.NewSize(...) with the smaller size capacity
   rb, err = rb.NewSize(5)
   if err != nil {
	   fmt.Println(err.Error())
   }
   if err = rb.WriteMany([]string{"test5","test6"}); err != nil {
	   fmt.Println(err.Error())
   }

   // newRb.Read() == []string{"test2", "test3", "test4", "test5", "test6"}
   fmt.Println(rb.Read())
   
   // Reset the buffer
   rb.Reset()
   fmt.Println(rb.Read())   // rb.Read() == []string{}
}

Documentation

Index

• type BufferType
• type RingBuffer
  • func New[T BufferType](capacity int) (*RingBuffer[T], error)
  • func (rb *RingBuffer[T]) Capacity() int
  • func (rb *RingBuffer[T]) IsEmpty() bool
  • func (rb *RingBuffer[T]) IsFull() bool
  • func (rb *RingBuffer[T]) Length() int
  • func (rb *RingBuffer[T]) NewSize(capacity int) (*RingBuffer[T], error)
  • func (rb *RingBuffer[T]) Read() (result []T)
  • func (rb *RingBuffer[T]) Reset()
  • func (rb *RingBuffer[T]) Size() int
  • func (rb *RingBuffer[T]) String() string
  • func (rb *RingBuffer[T]) Write(value T)
  • func (rb *RingBuffer[T]) WriteMany(values []T) error

Types

type BufferType

type BufferType interface {
	int | int16 | int32 | int64 |
		byte | uint | uint16 | uint32 | uint64 |
		float32 | float64 | bool | string
}

BufferType provides constraints on the types that may be used for a New RingBuffer

type RingBuffer

type RingBuffer[T BufferType] struct {
	// contains filtered or unexported fields
}

RingBuffer is effectively a fixed-size container as a data structure. Fields defined in this struct are named in the context as a fixed-size container.

func New

func New[T BufferType](capacity int) (*RingBuffer[T], error)

New is effectively a constructor that creates a new ring buffer with a fixed, zero-indexed capacity and specified type constrained by the BufferType interface

func (*RingBuffer[T]) Capacity

func (rb *RingBuffer[T]) Capacity() int

Capacity returns the zero-indexed capacity of the ring buffer itself, as opposed to the number of elements within the buffer.

For getting the number of elements in a buffer, use Length()

func (*RingBuffer[T]) IsEmpty

func (rb *RingBuffer[T]) IsEmpty() bool

IsEmpty returns a boolean indicating if the number of elements or values within the buffer is zero. Additionally, the write index must be zero.

func (*RingBuffer[T]) IsFull

func (rb *RingBuffer[T]) IsFull() bool

IsFull returns a boolean indicating if the number of elements or values of the buffer equals the buffer capacity or size.

func (*RingBuffer[T]) Length

func (rb *RingBuffer[T]) Length() int

Length returns the number of elements or values within the buffer.

For getting the total capacity of the buffer, use Capacity() or Size()

func (*RingBuffer[T]) NewSize

func (rb *RingBuffer[T]) NewSize(capacity int) (*RingBuffer[T], error)

NewSize recreates a new ring buffer with a different capacity or size, but with the same data as the old ring buffer. The NEW capacity cannot be smaller than the number of values or elements contained in the OLD buffer.

func (*RingBuffer[T]) Read

func (rb *RingBuffer[T]) Read() (result []T)

Read returns the contents of the buffer in "First-In First-Out" (FIFO) order

func (*RingBuffer[T]) Reset

func (rb *RingBuffer[T]) Reset()

Reset deletes all data within the buffer by re-allocation but retains the same exact capacity

func (*RingBuffer[T]) Size

func (rb *RingBuffer[T]) Size() int

Size returns the zero-indexed capacity of the ring buffer itself, as opposed to the number of elements within the buffer.

Size works exactly the same as Capacity() because it calls Capacity() directly in order to retain backwards compatability.

For getting the number of elements in a buffer, use Length()

func (*RingBuffer[T]) String

func (rb *RingBuffer[T]) String() string

String converts the capacity, writeIndex pointer, count of elements, and contents of the ring buffer into a string, then returns that string

func (*RingBuffer[T]) Write

func (rb *RingBuffer[T]) Write(value T)

Write inserts one element into the thread-safe buffer, overwriting the oldest element (without error) if the buffer is full

func (*RingBuffer[T]) WriteMany

func (rb *RingBuffer[T]) WriteMany(values []T) error

WriteMany first checks if the number of values is greater than the buffer or if the length of values is zero. If either of those conditions are true, then their respective error is returned.

Otherwise, WriteMany iterates over each slice of elements or values passed into it and calls Write for each element / value.