BinBuf

Mutable byte buffer; the mutable counterpart to Bin.

Implements: Index[{...Int: Int, ...Range[Int]: Bin}], Assign[{...Int: Int, ...Range[Int]: Bin}]

Constructor

`BinBuf …`

Builds a buffer, optionally seeded with the contents of existing binary data.

Parameters

Name	Type	Description
`initial?`	`Bin`	initial contents

Example

let buf = BinBuf(b"hello")
assert_eq $buf.len 5

Methods

`(assign) index value`

Assigns a byte or byte range. Range assignment may grow or shrink the buffer.

let buf = BinBuf(b"foobar")
buf[0] = 70
buf[1..3] = b"XYZ"
assert_eq $buf.freeze() b"FXYZbar"

`(index) index`

Unlike StrBuf, BinBuf supports both scalar and range indexing and indexing:

let buf = BinBuf(b"foobar")
assert_eq $buf[0] 102
assert_eq $buf[2..4] b"ob"

`(sink)()`

Returns this buffer as a sink. Values are appended verbatim, making it suitable for pipeline and process-output capture.

Use precrimp to add a terminator per value.

`append value`

Appends value to the buffer. Str/Bin input is copied byte-for-byte (round-tripping non-UTF-8 bytes exactly); anything else is converted the same way str would convert it, written directly into the buffer.

Parameters

Name	Type	Description
`value`		value to append

Example

let buf = BinBuf()
buf.append b"foo"
buf.append "bar"
buf.append 42
assert_eq $buf.freeze() b"foobar42"

`clear()`

Empties the buffer, retaining its allocated capacity.

let buf = BinBuf(b"foobar")
buf.clear()
assert_eq $buf.len 0
buf.append b"x"
assert_eq $buf.freeze() b"x"

`contains needle -> Bool`

Tests whether the buffer's contents contain the given bytes.

Parameters

Name	Type	Description
`needle`	`Bin`	the bytes to find

Example

assert (BinBuf(b"foobar").contains b"oob")

`drain … -> Iter[Bin]`

Returns an iterator that removes and yields up to size bytes at a time from the front of the buffer as it's consumed.

Parameters

Name	Type	Description
`size?`	`Int`	maximum bytes per chunk (defaults to 512 KiB)

Example

let buf = BinBuf(b"hello world")
assert_eq [...buf.drain(4)] [b"hell", b"o wo", b"rld"]
assert_eq $buf.len 0

Draining never shifts the buffer's remaining contents proportionally to their length: consumed bytes are dropped by advancing an internal cursor, not by copying the tail down on every chunk. Other mutating methods (and freeze) settle this cursor transparently before they run, so indices passed to them are always relative to the buffer's current (undrained) content. Multiple drain iterators created from the same buffer share this cursor, so they interleave draining the same content rather than each redraining it independently.

`ends_with suffix -> Bool`

Tests whether the buffer's contents end with the given suffix.

Parameters

Name	Type	Description
`suffix`	`Bin`	the suffix bytes

Example

assert (BinBuf(b"foobar").ends_with b"bar")

`extend value`

Appends the raw bytes of value, which must be a Str or Bin.

Parameters

Name	Type	Description
`value`	`(Bin \| Str)`

Example

let buf = BinBuf(b"foo")
buf.extend b"bar"
assert_eq $buf.freeze() b"foobar"

`freeze() -> Bin`

Converts the buffer's current contents into an immutable Bin in place, without copying, and empties the buffer. The buffer stays usable afterward, and the returned value is unaffected by later mutation.

Example

let buf = BinBuf(b"abc")
let frozen = buf.freeze()
assert_eq $frozen b"abc"
assert_eq $buf.len 0
buf.append b"def"
assert_eq $frozen b"abc"

`insert index value`

Inserts value at the given byte index, shifting the rest of the buffer right in place. value may be a single byte value, or a Str/Bin slice.

Parameters

Name	Type	Description
`index`	`Int`	insertion point
`value`	`(Int \| Bin)`	Byte value (0-255) or binary data.

Example

let buf = BinBuf(b"foobar")
buf.insert 3 b"XYZ"
buf.insert 0 65
assert_eq $buf.freeze() b"AfooXYZbar"

`len() -> Int`

Returns the byte length of the buffer's current contents.

Example

assert_eq (BinBuf(b"hello").len) 5

`push *bytes`

Appends one or more raw byte values to the buffer.

Parameters

Name	Type	Description
`*bytes`	`Int`	byte values (0-255) to append

Example

let buf = BinBuf()
buf.push 104 105
assert_eq $buf.freeze() b"hi"

`remove index_or_range -> (Int | Bin)`

Removes and returns a byte or a range of bytes, shifting the rest of the buffer left in place. An Int index removes and returns a single byte; a Range removes and returns a Bin of the removed bytes.

Parameters

Name	Type	Description
`index_or_range`	`(Int \| Range[Int])`

Example

let buf = BinBuf(b"foobar")
assert_eq (buf.remove 0) 102
assert_eq $buf.freeze() b"oobar"

let buf2 = BinBuf(b"foobar")
assert_eq (buf2.remove (1..3)) b"oo"
assert_eq $buf2.freeze() b"fbar"

`starts_with prefix -> Bool`

Tests whether the buffer's contents start with the given prefix.

Parameters

Name	Type	Description
`prefix`	`Bin`	the prefix bytes

Example

assert (BinBuf(b"foobar").starts_with b"foo")

`truncate len`

Shrinks the buffer to len bytes, discarding anything past that point.

Parameters

Name	Type	Description
`len`	`Int`	new length

Example

let buf = BinBuf(b"foobar")
buf.truncate 3
assert_eq $buf.freeze() b"foo"