datastream/binary

Framing operations on Stream(BitArray).

Real byte sources (sockets, files, pipes) deliver bytes in arbitrary chunks. A frame may straddle chunks, several frames may sit in one chunk, or a chunk may end mid-prefix. Every framing combinator here owns the buffer needed to reassemble.

All combinators are lazy and chunk-boundary-aware; none of them materialises the full input.

Types

IncompleteFrame

</>

Truncation surfaced by length_prefixed when the input ends mid-frame.

expected is the number of bytes the combinator was waiting for — either prefix_size (when the prefix itself was short) or the declared payload length (when the prefix was complete but the payload was short). got is the number of bytes the stream actually delivered toward that requirement (always < expected).

pub type IncompleteFrame {
  IncompleteFrame(expected: Int, got: Int)
  FrameTooLarge(claimed: Int, max: Int)
}

Constructors

IncompleteFrame(expected: Int, got: Int)

```
FrameTooLarge(claimed: Int, max: Int)
```
The prefix declared a payload length exceeding max_frame_size.

Values

bytes

</>

pub fn bytes(
  over stream: datastream.Stream(BitArray),
) -> datastream.Stream(Int)

Yield each byte of each chunk in order, as Int in 0..255.

The trivial degenerate framing: bridges from Stream(BitArray) to Stream(Int) so callers can move into the byte-stream-shaped world without writing the per-byte unfold themselves.

delimited

</>

pub fn delimited(
  over stream: datastream.Stream(BitArray),
  on delimiter: BitArray,
) -> datastream.Stream(BitArray)

Yield delimiter-separated frames in source order, preserving empty frames between consecutive delimiters and the trailing frame after a trailing delimiter. The delimiter itself is NOT included in any emitted frame.

If the input does not end with a delimiter, the trailing partial frame is emitted as the last element.

fixed_size

</>

pub fn fixed_size(
  over stream: datastream.Stream(BitArray),
  size size: Int,
) -> datastream.Stream(BitArray)

Yield successive size-byte frames in source order. The trailing partial frame on EOF is discarded — by definition a fixed-size framing combinator cannot emit a frame of fewer than size bytes.

size MUST be >= 1. Other values are rejected at construction time with a panic per the datastream module-level invalid-argument policy.

length_prefixed

</>

pub fn length_prefixed(
  over stream: datastream.Stream(BitArray),
  prefix_size prefix_size: Int,
) -> datastream.Stream(Result(BitArray, IncompleteFrame))

length_prefixed_with

</>

pub fn length_prefixed_with(
  over stream: datastream.Stream(BitArray),
  prefix_size prefix_size: Int,
  max_frame_size max_frame_size: Int,
) -> datastream.Stream(Result(BitArray, IncompleteFrame))

Like length_prefixed, but with an explicit max_frame_size limit. Frames whose prefix claims more than max_frame_size bytes are rejected immediately with Error(FrameTooLarge(claimed:, max:)) without buffering the payload.