Bytes Buffer (bb) - Flexible I/O Buffer for Go

Package bb (bb.Buffer) provides a flexible, efficient I/O buffer implementation with advanced manipulation capabilities. It combines features of bytes. Buffer, bytes.Reader, and adds powerful seeking, slicing, and streaming operations.

Features

• 📦 Dynamic buffer with configurable initial size
• 🔍 Seekable - move read position forward/backward
• 📝 Multiple write methods - bytes, strings, runes, and direct writes
• 📖 Multiple read methods - bytes, strings, runes, delimited reads
• ✂️ Buffer slicing - fork sub-buffers without copying
• 🧮 Checksum calculation - built-in CRC32 support
• 🔄 Stream operations - ReadFrom/WriteTo with chunked transfers
• 🎯 Position management - discard, resume, and truncate operations
• 🧵 Thread-safe design for single goroutine usage

Installation

go get go.osspkg.com/bb

Quick Start

package main

import (
    "fmt"
    "go.osspkg.com/bb"
)

func main() {
    // Create a new buffer
    buf := bb.New(1024)
    
    // Write data
    buf.WriteString("Hello, ")
    buf.WriteByte('W')
    buf.WriteRune('o')
    buf.Write([]byte("rld!"))
    
    // Read data
    data := make([]byte, 13)
    buf.Read(data)
    fmt.Println(string(data)) // Output: Hello, World!
    
    // Reset and reuse
    buf.Reset()
    fmt.Println(buf.Len()) // Output: 0
}

Core Operations

Creating Buffers

// Create empty buffer with default size (1024)
buf := bb.New(0)

// Create buffer with custom size
buf := bb.New(4096)

// Create buffer from existing bytes
data := []byte("existing data")
buf := bb.FromBytes(data)

// Buffer is ready to use
fmt.Printf("Size: %d, Position: %d\n", buf.Size(), buf.Index())

Writing Operations

buf := bb.New(1024)

// Write various types
buf.Write([]byte("bytes "))
buf.WriteString("string ")
buf.WriteByte('B')
buf.WriteRune('界')

// Write at specific position
buf.WriteAt([]byte("INSERT"), 5)

// Stream from reader
reader := strings.NewReader("stream data")
buf.ReadFrom(reader)

Reading Operations

buf := bb.FromBytes([]byte("Hello\nWorld\nGo"))

// Read bytes
b, _ := buf.ReadByte() // 'H'

// Read until delimiter
line, _ := buf.ReadBytes('\n') // "ello\n"
// Position now at 'W'

// Read rune
r, size, _ := buf.ReadRune() // 'W', 1

// Read string
str, _ := buf.ReadString('\n') // "orld\n"

// Read next field
field, _ := buf.NextField("Go") // returns data before "Go"

Position Management

buf := bb.FromBytes([]byte("Hello World"))

// Get current position
pos := buf.Index() // 0

// Read some data
buf.ReadByte() // Reads 'H', position = 1

// Seek to different positions
buf.Seek(0, bb.SeekStart)  // Go to beginning
buf.Seek(-1, bb.SeekEnd)   // Go to last byte
buf.Seek(5, bb.SeekCurr)   // Move forward 5 bytes

// Discard bytes (move forward)
discarded := buf.Discard(10) // Returns actual bytes discarded

// Resume bytes (move backward)
resumed := buf.Resume(5) // Returns actual bytes resumed

Advanced Operations

Buffer Forking

original := bb.FromBytes([]byte("Hello World Buffer"))

// Create sub-buffer (data is copied)
sub := original.Fork(6, 5) // "World"

// Original remains unchanged
fmt.Println(original.String()) // "Hello World Buffer"
fmt.Println(sub.String())       // "World"

Checksum Calculation

buf := bb.FromBytes([]byte("Important data"))

// Calculate CRC32 checksum of entire buffer
sum := buf.Checksum(0, buf.Size())

// Calculate checksum of specific region
partial := buf.Checksum(5, 10)

Truncate with UTF-8 Awareness

buf := bb.FromBytes([]byte("Hello 世界"))

// Truncate to 8 bytes (aware of UTF-8 boundaries)
buf.Truncate(8) // Safely truncates at rune boundaries

fmt.Println(buf.String()) // "Hello 世" (not corrupted)

Streaming Operations

buf := bb.New(1024)

// Read from reader with custom chunk size
n, err := buf.ReadFromN(reader, 4096)

// Write to writer with custom chunk size
n, err := buf.WriteToN(writer, 1024)

// Default chunk size (MaxUint16)
buf.ReadFrom(reader)
buf.WriteTo(writer)

API Reference

Type Buffer

type Buffer struct { ... }

Creation

• New(size int) *Buffer - Create new buffer
• FromBytes(b []byte) *Buffer - Create from existing bytes

Basic Operations

• Reset() - Reset buffer (with capacity optimization)
• Bytes() []byte - Get all bytes
• String() string - Get as string
• Size() int - Total buffer size
• Len() int - Remaining bytes to read
• Index() int - Current read position
• Truncate(n int) - Truncate with UTF-8 awareness

Writing

• Write(p []byte) (int, error)
• WriteString(s string) (int, error)
• WriteByte(b byte) error
• WriteRune(r rune) (int, error)
• WriteAt(b []byte, off int64) (int, error)

Reading

• Read(p []byte) (int, error)
• ReadAt(p []byte, off int64) (int, error)
• ReadByte() (byte, error)
• ReadRune() (rune, int, error)
• ReadBytes(delim byte) ([]byte, error)
• ReadString(delim byte) (string, error)
• ReadNextBytes(delim []byte) ([]byte, error)
• ReadNextString(delim string) (string, error)
• NextField(sep string) ([]byte, error)

Position Control

• Seek(offset int64, whence int) (int64, error)
• Discard(n int) int
• Resume(n int) int
• Next(n int) []byte

Advanced

• Fork(offset, length int) *Buffer
• Checksum(offset, length int) uint32

Streaming

• ReadFrom(r io.Reader) (int64, error)
• ReadFromN(r io.Reader, size int) (int64, error)
• WriteTo(w io.Writer) (int64, error)
• WriteToN(w io.Writer, size int) (int64, error)

Constants

SeekStart // Seek from start
SeekCurr  // Seek from current position
SeekEnd   // Seek from end

Performance Considerations

• The buffer automatically grows as needed
• Reset with capacity optimization prevents excessive allocations
• UTF-8 aware truncation prevents character corruption
• Fork creates a copy - use for sub-buffers when needed
• Checksum uses optimized CRC32 table

License

This project is licensed under the BSD 3-Clause License - see the LICENSE file for details.