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

BinaryArgError

</>

Why a checked binary framing constructor refused its argument.

Returned by length_prefixed_checked, length_prefixed_with_checked, and fixed_size_checked. Lets the caller surface argument validation failures through Result instead of crashing the process — useful when the numeric argument comes from CLI flags, config files, or request parameters.

function names the constructor that rejected the value ("length_prefixed", "fixed_size") so a caller routing many checked constructors through the same handler can produce a meaningful error message.

pub type BinaryArgError {
  InvalidPrefixSize(function: String, given: Int)
  NotPositiveSize(function: String, given: Int)
}

Constructors

```
InvalidPrefixSize(function: String, given: Int)
```
length_prefixed requires prefix_size to be one of {1, 2, 4, 8}. given is the value the caller passed.
```
NotPositiveSize(function: String, given: Int)
```
fixed_size requires size to be >= 1. given is the value the caller passed.

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.

fixed_size_checked

</>

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

Like fixed_size, but returns the argument-validation failure as a Result instead of panicking. Use this when size comes from dynamic input (CLI, config, request parameters); the panicking fixed_size remains the right tool for trusted constants.

On success the stream behaves identically to fixed_size(over: stream, size: size).

The caller is responsible for closing stream if the constructor returns Error.

length_prefixed

</>

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

length_prefixed_checked

</>

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

Like length_prefixed, but returns the argument-validation failure as a Result instead of panicking. Use this when prefix_size comes from dynamic input (CLI, config, request parameters); the panicking length_prefixed remains the right tool for trusted constants.

On success the stream behaves identically to length_prefixed(over: stream, prefix_size: prefix_size).

The caller is responsible for closing stream if the constructor returns Error.

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.

length_prefixed_with_checked

</>

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

Like length_prefixed_with, but returns the argument-validation failure as a Result instead of panicking. Use this when prefix_size comes from dynamic input.