streambuf

package
v1.0.0-beta4 Latest Latest
Warning

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

Go to latest
Published: Oct 22, 2015 License: Apache-2.0 Imports: 6 Imported by: 0

Documentation

Overview

The streambuf module provides helpers for buffering multiple packet payloads and some general parsing functions. All parsing functions are re-entrant, that is if a parse function fails due do not having buffered enough bytes yet (error value ErrNoMoreBytes) the parser can be called again after appending more bytes to the buffer. Parsers potentially reading large amount of bytes might remember the last position. Additionally a Buffer can be marked as fixed. Fixed buffers to not support adding new data, plus ErrNoMoreBytes will never be returned. Instead if a parser decides it need more bytes ErrUnexpectedEOB will be returned.

Error handling: All functions that might fail, will return an error. The last error reported will be stored with the buffer itself. Instead of checking every single error one can use the Failed() and Err() methods to check if the buffer is still in a valid state and all parsing was successfull.

Index

Constants

This section is empty.

Variables

View Source
var ErrExpectedByteSequenceMismatch = errors.New("expected byte sequence did not match")
View Source
var ErrExpectedDigit = errors.New("Expected digit")
View Source
var ErrNoMoreBytes = errors.New("No more bytes")

Parse operation can not be continued. More bytes required. Only returned if buffer is not fixed

View Source
var ErrOperationNotAllowed = errors.New("Operation not allowed")

Error returned if Append or Write operation is not allowed due to the buffer being fixed

View Source
var ErrOutOfRange = errors.New("Data access out of range")
View Source
var ErrUnexpectedEOB = errors.New("unexpected end of buffer")

Parse operation failed cause of buffer snapped short + buffer is fixed.

Functions

This section is empty.

Types

type Buffer

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

A Buffer is a variable sized buffer of bytes with Read, Write and simple parsing methods. The zero value is an empty buffer ready for use.

A Buffer can be marked as fixed. In this case no data can be appended to the buffer anymore and parser/reader methods will fail with ErrUnexpectedEOB if they would expect more bytes to come. Mark buffers fixed if some slice was separated for further parsing first.

func New

func New(data []byte) *Buffer

New creates new extensible buffer from data slice being retained by the buffer.

func NewFixed

func NewFixed(data []byte) *Buffer

NewFixed create new fixed buffer from data slice being retained by the buffer.

func (*Buffer) Advance

func (b *Buffer) Advance(count int) error

Advance will advance the buffers read pointer by count bytes. Returns ErrNoMoreBytes or ErrUnexpectedEOB if count bytes are not available.

func (*Buffer) Append

func (b *Buffer) Append(data []byte) error

Append will append the given data to the buffer. If Buffer is fixed ErrOperationNotAllowed will be returned.

func (*Buffer) AsciiInt

func (b *Buffer) AsciiInt(errOnEnd bool) (int64, error)

AsciiInt will parse (optionally) signed number from Buffer.

func (*Buffer) AsciiMatch

func (b *Buffer) AsciiMatch(prefix []byte) (bool, error)

AsciiMatch checks the Buffer it's next byte sequence matched prefix. The read pointer is not advanced by AsciiPrefix.

func (*Buffer) AsciiUint

func (b *Buffer) AsciiUint(errOnEnd bool) (uint64, error)

AsciiUint will parse unsigned number from Buffer.

func (*Buffer) Avail

func (b *Buffer) Avail(count int) bool

Avail checks if count bytes are available for reading from the buffer.

func (*Buffer) BufferConsumed

func (b *Buffer) BufferConsumed() int

BufferConsumed returns the number of bytes already consumed since last call to Reset.

func (*Buffer) BufferedBytes

func (b *Buffer) BufferedBytes() []byte

BufferedBytes returns all buffered bytes since last reset.

func (*Buffer) Bytes

func (b *Buffer) Bytes() []byte

Bytes returns all bytes not yet processed. The read counters are not advanced yet. For example use with fixed Buffer for simple lookahead.

Note: The read markers are not advanced. If rest of buffer should be processed, call Advance immediately.

func (*Buffer) Collect

func (b *Buffer) Collect(count int) ([]byte, error)

Collect tries to collect count bytes from the buffer and updates the read pointers. If the buffer is in failed state or count bytes are not available an error will be returned.

func (*Buffer) CollectWithSuffix

func (b *Buffer) CollectWithSuffix(count int, delim []byte) ([]byte, error)

CollectWithDelimiter collects count bytes and checks delim will immediately follow the byte sequence. Returns count bytes without delim. If delim is not matched ErrExpectedByteSequenceMismatch will be raised.

func (*Buffer) Consume

func (b *Buffer) Consume(n int) ([]byte, error)

Consume removes the first n bytes (special variant of Reset) from the beginning of the buffer, if at least n bytes have already been processed. Returns the byte slice of all bytes being removed from the buffer. If total buffer is < n, ErrOutOfRange will be reported or ErrOutOfRange if not enough bytes have been processed yet.

func (*Buffer) Err

func (b *Buffer) Err() error

Returns the error value of the last failed operation.

func (*Buffer) Failed

func (b *Buffer) Failed() bool

Failed returns true if buffer is in failed state. If buffer is in failed state, almost all buffer operations will fail

func (*Buffer) Fix

func (b *Buffer) Fix()

Fix marks a buffer as fixed. No more data can be added to the buffer and parse operation might fail if they expect more bytes.

func (*Buffer) IgnoreSymbol

func (b *Buffer) IgnoreSymbol(s uint8) error

Ignore symbol will advance the read pointer until the first symbol not matching s is found.

func (*Buffer) Init

func (b *Buffer) Init(d []byte, fixed bool)

Init initializes a zero buffer with some byte slice being retained by the buffer. Usage of Init is optional as zero value Buffer is already in valid state.

func (*Buffer) LeftBehind

func (b *Buffer) LeftBehind() int

LeftBehind returns the number of bytes a re-entrant but not yet finished parser did already read.

func (*Buffer) Len

func (b *Buffer) Len() int

Len returns the number of bytes of the unread portion.

func (*Buffer) Read

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

Read reads up to len(p) bytes into p if buffer is not in a failed state. Returns ErrNoMoreBytes or io.EOF (fixed buffer) if no bytes are available.

func (*Buffer) ReadAt

func (b *Buffer) ReadAt(p []byte, off int64) (n int, err error)

ReadAt reads bytes at off into p starting at the buffer its read marker. The read marker is not updated. If number of bytes returned is less len(p) or no bytes are available at off, io.EOF will be returned in err. If off is < 0, err is set to ErrOutOfRange.

func (*Buffer) ReadByte

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

ReadByte reads and returns next byte from the buffer. If no byte is available returns either ErrNoMoreBytes (if buffer allows adding more bytes) or io.EOF

func (*Buffer) ReadFrom

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

ReadFrom reads data from r until error or io.EOF and appends it to the buffer. The amount of bytes read is returned plus any error except io.EOF.

func (*Buffer) ReadNetUint16

func (b *Buffer) ReadNetUint16() (uint16, error)

Parse 16bit binary value in network byte order from Buffer (converted to Host order).

func (*Buffer) ReadNetUint16At

func (b *Buffer) ReadNetUint16At(index int) (uint16, error)

Parse 16bit binary value from the buffer at index. Will not advance the read buffer

func (*Buffer) ReadNetUint32

func (b *Buffer) ReadNetUint32() (uint32, error)

Parse 32bit binary value in network byte order from Buffer (converted to Host order).

func (*Buffer) ReadNetUint32At

func (b *Buffer) ReadNetUint32At(index int) (uint32, error)

Parse 32bit binary value from the buffer at index. Will not advance the read buffer

func (*Buffer) ReadNetUint64

func (b *Buffer) ReadNetUint64() (uint64, error)

Parse 64bit binary value in network byte order from Buffer (converted to Host order).

func (*Buffer) ReadNetUint64At

func (b *Buffer) ReadNetUint64At(index int) (uint64, error)

Parse 64bit binary value from the buffer at index. Will not advance the read buffer

func (*Buffer) ReadNetUint8

func (b *Buffer) ReadNetUint8() (uint8, error)

Parse 8bit binary value from Buffer.

func (*Buffer) ReadNetUint8At

func (b *Buffer) ReadNetUint8At(index int) (uint8, error)

Parse 8bit binary value from the buffer at index. Will not advance the read buffer

func (*Buffer) ReadRune

func (b *Buffer) ReadRune() (rune, int, error)

ReadRune reads and returns the next UTF-8-encoded Unicode code point from the buffer. If no bytes are available, the error returned is ErrNoMoreBytes (if buffer supports adding more bytes) or io.EOF. If the bytes are an erroneous UTF-8 encoding, it consumes one byte and returns U+FFFD, 1.

func (*Buffer) Reset

func (b *Buffer) Reset()

Reset remove all bytes already processed from the buffer. Use Reset after processing message to limit amount of buffered data.

func (*Buffer) Restore

func (b *Buffer) Restore(snapshot *Buffer)

Restore restores a buffers state. Use in conjunction with Snapshot to get simple backtracking support. Between Snapshot and Restore the Reset method MUST not be called, as restored buffer will be in invalid state after.

func (*Buffer) SetError

func (b *Buffer) SetError(err error) error

SetError marks a buffer as failed. Append and parse operations will fail with err. SetError returns err directly.

func (*Buffer) Snapshot

func (b *Buffer) Snapshot() *Buffer

Snapshot creates a snapshot of buffers current state. Use in conjunction with Restore to get simple backtracking support. Between Snapshot and Restore the Reset method MUST not be called, as restored buffer will be in invalid state after.

func (*Buffer) Total

func (b *Buffer) Total() int

Total returns the total number of bytes stored in the buffer

func (*Buffer) UnreadByte

func (b *Buffer) UnreadByte() error

Unreads the last byte returned by most recent read operation.

func (*Buffer) UntilCRLF

func (b *Buffer) UntilCRLF() ([]byte, error)

UntilCRLF collects all bytes until a CRLF ("\r\n") sequence is found. The returned byte slice will not contain the CRLF sequence. If CRLF was not found yet one of ErrNoMoreBytes or ErrUnexpectedEOB will be reported.

func (*Buffer) UntilSymbol

func (b *Buffer) UntilSymbol(s uint8, errOnEnd bool) ([]byte, error)

UntilSymbol collects all bytes until symbol s is found. If errOnEnd is set to true, the collected byte slice will be returned if no more bytes are available for parsing, but s has not matched yet.

func (*Buffer) Write

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

Write writes p to the buffer if buffer is not fixed. Returns the number of bytes written or ErrOperationNotAllowed if buffer is fixed.

func (*Buffer) WriteAt

func (b *Buffer) WriteAt(p []byte, off int64) (n int, err error)

WriteAt writes the content of p at off starting at recent read marker (already consumed bytes). Returns number of bytes written n = len(p) and err is nil if off and off+len(p) are within bounds, else n=0 and err is set to ErrOutOfRange.

func (*Buffer) WriteByte

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

WriteByte appends the byte c to the buffer if buffer is not fixed.

func (*Buffer) WriteNetUint16

func (b *Buffer) WriteNetUint16(u uint16) error

Write 16bit binary value in network byte order to buffer.

func (*Buffer) WriteNetUint16At

func (b *Buffer) WriteNetUint16At(u uint16, index int) error

Write 16bit binary value at index in network byte order to buffer.

func (*Buffer) WriteNetUint32

func (b *Buffer) WriteNetUint32(u uint32) error

Write 32bit binary value in network byte order to buffer.

func (*Buffer) WriteNetUint32At

func (b *Buffer) WriteNetUint32At(u uint32, index int) error

Write 32bit binary value at index in network byte order to buffer.

func (*Buffer) WriteNetUint64

func (b *Buffer) WriteNetUint64(u uint64) error

Write 64bit binary value in network byte order to buffer.

func (*Buffer) WriteNetUint64At

func (b *Buffer) WriteNetUint64At(u uint64, index int) error

Write 64bit binary value at index in network byte order to buffer.

func (*Buffer) WriteNetUint8

func (b *Buffer) WriteNetUint8(u uint8) error

Write 8bit binary value to Buffer.

func (*Buffer) WriteNetUint8At

func (b *Buffer) WriteNetUint8At(u uint8, index int) error

Write 8bit binary value at index.

Jump to

Keyboard shortcuts

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