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 ¶
- Variables
- type Buffer
- func (b *Buffer) Advance(count int) error
- func (b *Buffer) Append(data []byte) error
- func (b *Buffer) AppendWithCapLimits(data []byte, newCap int) error
- func (b *Buffer) AsciiInt(errOnEnd bool) (int64, error)
- func (b *Buffer) AsciiMatch(prefix []byte) (bool, error)
- func (b *Buffer) AsciiUint(errOnEnd bool) (uint64, error)
- func (b *Buffer) Avail(count int) bool
- func (b *Buffer) BufferConsumed() int
- func (b *Buffer) BufferedBytes() []byte
- func (b *Buffer) Bytes() []byte
- func (b *Buffer) Cap() int
- func (b *Buffer) Collect(count int) ([]byte, error)
- func (b *Buffer) CollectUntil(delim []byte) ([]byte, error)
- func (b *Buffer) CollectUntilByte(delim byte) ([]byte, error)
- func (b *Buffer) CollectWithSuffix(count int, delim []byte) ([]byte, error)
- func (b *Buffer) Consume(n int) ([]byte, error)
- func (b *Buffer) Err() error
- func (b *Buffer) Failed() bool
- func (b *Buffer) Fix()
- func (b *Buffer) IgnoreSymbol(s uint8) error
- func (b *Buffer) Index(seq []byte) int
- func (b *Buffer) IndexByte(byte byte) int
- func (b *Buffer) IndexFrom(from int, seq []byte) int
- func (b *Buffer) Init(d []byte, fixed bool)
- func (b *Buffer) LeftBehind() int
- func (b *Buffer) Len() int
- func (b *Buffer) Read(p []byte) (int, error)
- func (b *Buffer) ReadAt(p []byte, off int64) (n int, err error)
- func (b *Buffer) ReadByte() (byte, error)
- func (b *Buffer) ReadFrom(r io.Reader) (int64, error)
- func (b *Buffer) ReadNetUint16() (uint16, error)
- func (b *Buffer) ReadNetUint16At(index int) (uint16, error)
- func (b *Buffer) ReadNetUint32() (uint32, error)
- func (b *Buffer) ReadNetUint32At(index int) (uint32, error)
- func (b *Buffer) ReadNetUint64() (uint64, error)
- func (b *Buffer) ReadNetUint64At(index int) (uint64, error)
- func (b *Buffer) ReadNetUint8() (uint8, error)
- func (b *Buffer) ReadNetUint8At(index int) (uint8, error)
- func (b *Buffer) ReadRune() (rune, int, error)
- func (b *Buffer) Reset()
- func (b *Buffer) Restore(snapshot *Buffer)
- func (b *Buffer) SetError(err error) error
- func (b *Buffer) Snapshot() *Buffer
- func (b *Buffer) Total() int
- func (b *Buffer) UnreadByte() error
- func (b *Buffer) UntilCRLF() ([]byte, error)
- func (b *Buffer) UntilSymbol(s uint8, errOnEnd bool) ([]byte, error)
- func (b *Buffer) Write(p []byte) (int, error)
- func (b *Buffer) WriteAt(p []byte, off int64) (n int, err error)
- func (b *Buffer) WriteByte(c byte) error
- func (b *Buffer) WriteNetUint16(u uint16) error
- func (b *Buffer) WriteNetUint16At(u uint16, index int) error
- func (b *Buffer) WriteNetUint32(u uint32) error
- func (b *Buffer) WriteNetUint32At(u uint32, index int) error
- func (b *Buffer) WriteNetUint64(u uint64) error
- func (b *Buffer) WriteNetUint64At(u uint64, index int) error
- func (b *Buffer) WriteNetUint8(u uint8) error
- func (b *Buffer) WriteNetUint8At(u uint8, index int) error
Constants ¶
This section is empty.
Variables ¶
var ErrExpectedByteSequenceMismatch = errors.New("expected byte sequence did not match")
var ErrExpectedDigit = errors.New("Expected digit")
var ErrNoMoreBytes = errors.New("No more bytes")
Parse operation can not be continued. More bytes required. Only returned if buffer is not fixed
var ErrOperationNotAllowed = errors.New("Operation not allowed")
Error returned if Append or Write operation is not allowed due to the buffer being fixed
var ErrOutOfRange = errors.New("Data access out of range")
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 (*Buffer) Advance ¶
Advance will advance the buffers read pointer by count bytes. Returns ErrNoMoreBytes or ErrUnexpectedEOB if count bytes are not available.
func (*Buffer) Append ¶
Append will append the given data to the buffer. If Buffer is fixed ErrOperationNotAllowed will be returned.
func (*Buffer) AppendWithCapLimits ¶
func (*Buffer) AsciiMatch ¶
AsciiMatch checks the Buffer it's next byte sequence matched prefix. The read pointer is not advanced by AsciiPrefix.
func (*Buffer) BufferConsumed ¶
BufferConsumed returns the number of bytes already consumed since last call to Reset.
func (*Buffer) BufferedBytes ¶
BufferedBytes returns all buffered bytes since last reset.
func (*Buffer) Bytes ¶
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 ¶
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) CollectUntil ¶
CollectUntil collects all bytes until delim was found (including delim).
func (*Buffer) CollectUntilByte ¶
CollectUntilByte collects all bytes until delim was found (including delim).
func (*Buffer) CollectWithSuffix ¶
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 ¶
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) Failed ¶
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 ¶
Ignore symbol will advance the read pointer until the first symbol not matching s is found.
func (*Buffer) Index ¶
Index returns offset of seq in unprocessed buffer. Returns -1 if seq can not be found.
func (*Buffer) IndexByte ¶
IndexByte returns offset of byte in unprocessed buffer. Returns -1 if byte not in buffer.
func (*Buffer) IndexFrom ¶
IndexFrom returns offset of seq in unprocessed buffer start at from. Returns -1 if seq can not be found.
func (*Buffer) Init ¶
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 ¶
LeftBehind returns the number of bytes a re-entrant but not yet finished parser did already read.
func (*Buffer) Read ¶
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 ¶
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 ¶
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 ¶
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 ¶
Parse 16bit binary value in network byte order from Buffer (converted to Host order).
func (*Buffer) ReadNetUint16At ¶
Parse 16bit binary value from the buffer at index. Will not advance the read buffer
func (*Buffer) ReadNetUint32 ¶
Parse 32bit binary value in network byte order from Buffer (converted to Host order).
func (*Buffer) ReadNetUint32At ¶
Parse 32bit binary value from the buffer at index. Will not advance the read buffer
func (*Buffer) ReadNetUint64 ¶
Parse 64bit binary value in network byte order from Buffer (converted to Host order).
func (*Buffer) ReadNetUint64At ¶
Parse 64bit binary value from the buffer at index. Will not advance the read buffer
func (*Buffer) ReadNetUint8 ¶
Parse 8bit binary value from Buffer.
func (*Buffer) ReadNetUint8At ¶
Parse 8bit binary value from the buffer at index. Will not advance the read buffer
func (*Buffer) ReadRune ¶
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 ¶
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 ¶
SetError marks a buffer as failed. Append and parse operations will fail with err. SetError returns err directly.
func (*Buffer) Snapshot ¶
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) UnreadByte ¶
Unreads the last byte returned by most recent read operation.
func (*Buffer) UntilCRLF ¶
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 ¶
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 ¶
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 ¶
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) WriteNetUint16 ¶
Write 16bit binary value in network byte order to buffer.
func (*Buffer) WriteNetUint16At ¶
Write 16bit binary value at index in network byte order to buffer.
func (*Buffer) WriteNetUint32 ¶
Write 32bit binary value in network byte order to buffer.
func (*Buffer) WriteNetUint32At ¶
Write 32bit binary value at index in network byte order to buffer.
func (*Buffer) WriteNetUint64 ¶
Write 64bit binary value in network byte order to buffer.
func (*Buffer) WriteNetUint64At ¶
Write 64bit binary value at index in network byte order to buffer.
func (*Buffer) WriteNetUint8 ¶
Write 8bit binary value to Buffer.
Source Files