buffer

README

buffer

Ring buffers in Go.

Documentation

Overview

Package buffer implements ring buffers of bytes.

Index

• type Buffer
  • func New(numBits byte) *Buffer
  • func (b Buffer) Cap() uint
  • func (b *Buffer) Clear()
  • func (b *Buffer) CommitBulkRead(length uint)
  • func (b *Buffer) CommitBulkWrite(length uint)
  • func (b Buffer) DebugString() string
  • func (b Buffer) GoString() string
  • func (b *Buffer) Init(numBits byte)
  • func (b Buffer) IsEmpty() bool
  • func (b Buffer) IsFull() bool
  • func (b Buffer) Len() uint
  • func (b Buffer) NumBits() byte
  • func (b *Buffer) PrepareBulkRead(length uint) []byte
  • func (b *Buffer) PrepareBulkWrite(length uint) []byte
  • func (b *Buffer) Read(p []byte) (int, error)
  • func (b *Buffer) ReadByte() (byte, error)
  • func (b *Buffer) ReadFrom(r io.Reader) (int64, error)
  • func (b Buffer) String() string
  • func (b *Buffer) Write(p []byte) (int, error)
  • func (b *Buffer) WriteByte(ch byte) error
  • func (b *Buffer) WriteTo(w io.Writer) (int64, error)
• type Error
  • func (err Error) Error() string
  • func (err Error) GoString() string
• type Window
  • func NewWindow(numBits byte) *Window
  • func (w Window) Cap() uint
  • func (w *Window) Clear()
  • func (w Window) DebugString() string
  • func (w Window) FindLongestPrefix(p []byte) (distance uint, length uint, ok bool)
  • func (w Window) GoString() string
  • func (w Window) Hash(hashes ...hash.Hash)
  • func (w Window) Hash32(fn func() hash.Hash32) uint32
  • func (w *Window) Init(numBits byte)
  • func (w Window) IsEmpty() bool
  • func (w Window) IsFull() bool
  • func (w Window) Len() uint
  • func (w Window) LookupByte(distance uint) (byte, error)
  • func (w Window) NumBits() byte
  • func (w Window) String() string
  • func (w *Window) Write(p []byte) (int, error)
  • func (w *Window) WriteByte(ch byte) error

Types

type Buffer

type Buffer struct {
	// contains filtered or unexported fields
}

Buffer implements a ring buffer. The ring buffer has space for 2**N bytes for user-specified N.

func New

func New(numBits byte) *Buffer

New is a convenience function that allocates a new Buffer and calls Init on it.

func (Buffer) Cap

func (b Buffer) Cap() uint

Cap returns the maximum byte capacity of the Buffer.

func (*Buffer) Clear

func (b *Buffer) Clear()

Clear erases the contents of the Buffer.

func (*Buffer) CommitBulkRead

func (b *Buffer) CommitBulkRead(length uint)

CommitBulkRead completes the bulk read begun by the previous call to PrepareBulkRead. The argument must be between 0 and the length of the slice returned by PrepareBulkRead.

func (*Buffer) CommitBulkWrite

func (b *Buffer) CommitBulkWrite(length uint)

CommitBulkWrite completes the bulk write begun by the previous call to PrepareBulkWrite. The argument must be between 0 and the length of the slice returned by PrepareBulkWrite.

func (Buffer) DebugString

func (b Buffer) DebugString() string

DebugString returns a detailed dump of the Buffer's internal state.

func (Buffer) GoString

func (b Buffer) GoString() string

GoString returns a brief dump of the Buffer's internal state.

func (*Buffer) Init

func (b *Buffer) Init(numBits byte)

Init initializes the Buffer. The Buffer will hold a maximum of 2**N bits, where N is the argument provided. The argument must be a number between 0 and 31 inclusive.

func (Buffer) IsEmpty

func (b Buffer) IsEmpty() bool

IsEmpty returns true iff the Buffer contains no bytes.

func (Buffer) IsFull

func (b Buffer) IsFull() bool

IsFull returns true iff the Buffer contains the maximum number of bytes.

func (Buffer) Len

func (b Buffer) Len() uint

Len returns the number of bytes currently in the Buffer.

func (Buffer) NumBits

func (b Buffer) NumBits() byte

NumBits returns the number of bits used to initialize this Buffer.

func (*Buffer) PrepareBulkRead

func (b *Buffer) PrepareBulkRead(length uint) []byte

PrepareBulkRead obtains a slice from which the caller can read bytes. The bytes do not leave the buffer's contents until CommitBulkRead is called. If CommitBulkRead is not subsequently called, the read acts as a "peek" operation.

The returned slice may contain fewer bytes than requested; it will return a zero-length slice iff the buffer is empty. The caller must check its length before using it. A short but non-empty return slice does *not* indicate an empty buffer.

The returned slice is only valid until the next call to any mutating method on this Buffer; mutating methods are those which take a pointer receiver.

func (*Buffer) PrepareBulkWrite

func (b *Buffer) PrepareBulkWrite(length uint) []byte

PrepareBulkWrite obtains a slice into which the caller can write bytes. The bytes do not become a part of the buffer's contents until CommitBulkWrite is called. If CommitBulkWrite is not subsequently called, the write is considered abandoned.

The returned slice may contain fewer bytes than requested; it will return a nil slice iff the buffer is full. The caller must check the slice's length before using it. A short but non-empty return slice does *not* indicate a full buffer.

The returned slice is only valid until the next call to any mutating method on this Buffer; mutating methods are those which take a pointer receiver.

func (*Buffer) Read

func (b *Buffer) Read(p []byte) (int, error)

Read reads a slice of bytes from the Buffer. If the buffer is empty, ErrEmpty is returned.

func (*Buffer) ReadByte

func (b *Buffer) ReadByte() (byte, error)

ReadByte reads a single byte from the Buffer. If the buffer is empty, ErrEmpty is returned.

func (*Buffer) ReadFrom

func (b *Buffer) ReadFrom(r io.Reader) (int64, error)

ReadFrom attempts to fill this Buffer by reading from the provided Reader. May return any error returned by the Reader, including io.EOF. If a nil error is returned, then the buffer is now full.

func (Buffer) String

func (b Buffer) String() string

String returns a plain-text description of the buffer.

func (*Buffer) Write

func (b *Buffer) Write(p []byte) (int, error)

Write writes a slice of bytes to the Buffer. If the Buffer is full, as many bytes as possible are written to the Buffer and ErrFull is returned.

func (*Buffer) WriteByte

func (b *Buffer) WriteByte(ch byte) error

WriteByte writes a single byte to the Buffer. If the Buffer is full, ErrFull is returned.

func (*Buffer) WriteTo

func (b *Buffer) WriteTo(w io.Writer) (int64, error)

WriteTo attempts to drain this Buffer by writing to the provided Writer. May return any error returned by the Writer. If a nil error is returned, then the Buffer is now empty.

type Error

type Error byte

Error is the type for the error constants returned by this package.

const (
	// ErrEmpty is returned when reading from an empty Buffer.
	ErrEmpty Error = iota

	// ErrFull is returned when writing to a full Buffer.
	ErrFull

	// ErrBadDistance is returned when Window.LookupByte is called with a
	// distance that isn't contained within the Window.
	ErrBadDistance
)

func (Error) Error

func (err Error) Error() string

Error returns the error message for this error.

func (Error) GoString

func (err Error) GoString() string

GoString returns the name of the Go constant.

type Window

type Window struct {
	// contains filtered or unexported fields
}

Window implements a sliding window backed by a ring buffer. The ring buffer has space for 2**N bytes for user-specified N.

func NewWindow

func NewWindow(numBits byte) *Window

NewWindow is a convenience function that allocates a Window and calls Init on it.

func (Window) Cap

func (w Window) Cap() uint

Cap returns the maximum byte capacity of the Window.

func (*Window) Clear

func (w *Window) Clear()

Clear erases the contents of the Window.

func (Window) DebugString

func (w Window) DebugString() string

DebugString returns a detailed dump of the Window's internal state.

func (Window) FindLongestPrefix

func (w Window) FindLongestPrefix(p []byte) (distance uint, length uint, ok bool)

FindLongestPrefix searches the Window for the longest prefix of the given byte slice that exists within the Window's history.

This method could use some additional optimization.

func (Window) GoString

func (w Window) GoString() string

GoString returns a brief dump of the Window's internal state.

func (Window) Hash

func (w Window) Hash(hashes ...hash.Hash)

Hash non-destructively writes the contents of the Window into the provided Hash object(s).

func (Window) Hash32

func (w Window) Hash32(fn func() hash.Hash32) uint32

Hash32 is a convenience method that constructs a Hash32, calls Window.Hash with it, and calls Sum32 on it.

func (*Window) Init

func (w *Window) Init(numBits byte)

Init initializes the Window. The Window will hold a maximum of 2**N bits, where N is the argument provided. The argument must be a number between 0 and 31 inclusive.

func (Window) IsEmpty

func (w Window) IsEmpty() bool

IsEmpty returns true iff the Window contains no bytes.

func (Window) IsFull

func (w Window) IsFull() bool

IsFull returns true iff the Window contains the maximum number of bytes.

func (Window) Len

func (w Window) Len() uint

Len returns the number of bytes currently in the Window.

func (Window) LookupByte

func (w Window) LookupByte(distance uint) (byte, error)

LookupByte returns a byte which was written previously. The argument is the offset into the window, with 1 representing the most recently written byte and Window.Cap() representing the oldest byte still within the Window.

func (Window) NumBits

func (w Window) NumBits() byte

NumBits returns the number of bits used to initialize this Window.

func (Window) String

func (w Window) String() string

String returns a plain-text description of the buffer.

func (*Window) Write

func (w *Window) Write(p []byte) (int, error)

Write writes a slice of bytes to the Window. If the Window is full or if the slice exceeds the capacity of the Window, the oldest bytes in the inferred stream are dropped until the slice fits.

func (*Window) WriteByte

func (w *Window) WriteByte(ch byte) error

WriteByte writes a single byte to the Window. If the Window is full, the oldest byte in the inferred stream is dropped.