Documentation
¶
Overview ¶
Package bytestream reads binary formats a field at a time.
A Stream tracks a byte position and an intra-byte bit position, so sub-byte fields compose without the caller doing the shifting. Moving outside the buffer panics with a StreamError rather than returning one: a parser that has walked off the end has misread its input and cannot usefully continue, so the caller recovers once at the point where giving up makes sense instead of checking after every read.
Index ¶
- type Stream
- func (s *Stream) Advance(n int)
- func (s *Stream) At(i int) int
- func (s *Stream) Carve(start, finish int) []byte
- func (s *Stream) Clone() *Stream
- func (s *Stream) ConsumeIf(val byte)
- func (s *Stream) ConsumeWhile(val byte)
- func (s *Stream) ContinueUntil(seq []byte)
- func (s *Stream) ContinueUntilByte(val byte)
- func (s *Stream) GetBytes(numBytes int) []byte
- func (s *Stream) HasMore() bool
- func (s *Stream) Length() int
- func (s *Stream) LookingAt(seq []byte) bool
- func (s *Stream) MoveBackwardsBy(n int)
- func (s *Stream) MoveForwardsBy(n int)
- func (s *Stream) MoveTo(pos int)
- func (s *Stream) Peek(i int) byte
- func (s *Stream) ReadBits(numBits int) int
- func (s *Stream) ReadInt(numBytes int) int
- func (s *Stream) ReadIntLE(numBytes int) int
- func (s *Stream) ReadIntOrder(numBytes int, little bool) int
- func (s *Stream) ReadString(numBytes int) string
- type StreamError
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Stream ¶
Stream is a port of CyberChef's lib/Stream.mjs: a byte reader tracking a byte position and an intra-byte bit position. The packet parsers use the reading half; the file carvers additionally seek about and slice pieces out.
func New ¶
New returns a stream positioned at the start of b. The stream reads b in place and never copies it.
func (*Stream) Advance ¶
Advance moves the position by n without requiring the result to lie inside the buffer. Stream.mjs has no such method: the carvers that need it assign to `position` directly, which skips the bounds check that moveForwardsBy makes, and rely on running off the end to finish a loop. Moving to before the start is still refused, as no read could follow it.
func (*Stream) Carve ¶
Carve returns the bytes between start and finish. A part-read byte at finish is taken whole, as the bits already consumed belong to the carved region.
func (*Stream) Clone ¶
Clone returns a reader over the same bytes at the same position. The two then move independently, which lets a carver look ahead without losing its place.
func (*Stream) ConsumeWhile ¶
ConsumeWhile advances over a run of val.
func (*Stream) ContinueUntil ¶
ContinueUntil moves to the start of the next occurrence of seq at or after the current position, or to the end of the buffer if there is none.
CyberChef's Stream.ContinueUntil takes a different path for a sequence than for a single byte: it abandons the current position and scans from the length of the sequence, and its skip table is indexed by the pattern byte that failed rather than the text byte found, so the scan can step over a match that is there. Both are defects — the callers all mean "find the next one from here" — so this searches plainly forwards instead. On well-formed input the two agree.
func (*Stream) ContinueUntilByte ¶
ContinueUntilByte moves to the next occurrence of val, or to the end of the buffer if there is none. The byte under the current position is skipped, so repeated calls walk successive occurrences rather than standing still.
func (*Stream) GetBytes ¶
GetBytes returns numBytes bytes from the current position (all remaining when numBytes < 0), advancing the position and clearing the bit position.
func (*Stream) LookingAt ¶
LookingAt reports whether seq sits at the current position, without moving.
func (*Stream) MoveBackwardsBy ¶
MoveBackwardsBy retreats the stream position by n bytes.
func (*Stream) MoveForwardsBy ¶
MoveForwardsBy advances the stream position by n bytes.
func (*Stream) MoveTo ¶
MoveTo sets the stream position, which must lie within the buffer. The end of the buffer counts as within it: that is where a read of the last byte lands.
func (*Stream) Peek ¶
Peek returns the byte at absolute position i without moving the stream. A position outside the buffer is an out-of-bounds read, as for a move.
func (*Stream) ReadBits ¶
ReadBits reads numBits big-endian bits, tracking the intra-byte position so successive sub-byte reads compose correctly.
func (*Stream) ReadIntOrder ¶
ReadIntOrder reads an integer in either byte order. Bytes past the end of the buffer read as zero, as indexing past a Uint8Array yields undefined and the JS bitwise operators coerce that to 0.
func (*Stream) ReadString ¶
ReadString reads numBytes bytes as a string, stopping the string at the first null byte but still consuming the whole width. A negative width reads to the end.
type StreamError ¶
type StreamError struct{ Pos int }
StreamError is raised when a stream is asked to move outside its buffer. Stream.mjs throws in the same places, and a carver that walks off the end of its buffer has misread the file and must abandon the carve; unwinding to the boundary that owns the read keeps that check out of every read, where a recovery turns it back into an ordinary error value.
func (StreamError) Error ¶
func (e StreamError) Error() string
Source Files