Struct Builder 

pub struct Builder { /* private fields */ }

Assembles IoBufs from a mix of inline writes and zero-copy pieces.

All inline writes go into a single buffer, and BufsMut::push records the inline offset at which each pushed piece belongs. Builder::finish freezes the buffer once, splits it at those offsets with IoBuf::split_to, and interleaves the pushed chunks with the inline segments.

A pushed IoBuf becomes a chunk as is. Any other pushed value converts into Bytes, and the chunk owns that Bytes without copying.

The inline buffer has a fixed capacity set at construction and will not grow. Callers must ensure the capacity accounts for all inline (non-pushed) bytes that will be written. Exceeding it will panic.

builder.put_u16(99);                   // inline
builder.push(shard_payload.clone());   // zero-copy: shares the Bytes
builder.put_u32(checksum);             // inline
let output = builder.finish();

// inline buffer  [ 99 | checksum ]           one allocation, frozen once
// pushed Bytes   [ ----- 1 MB shard ----- ]  the caller's, never copied
//
// output         [ 99 ][ ----- 1 MB shard ----- ][ checksum ]
//                 inline      pushed Bytes           inline

Implementations

impl Builder

pub fn new(capacity: usize) -> Self

Creates a builder whose inline buffer holds exactly capacity bytes.

A zero capacity allocates nothing, so the builder accepts only pushed chunks.

Panics

Panics if capacity exceeds isize::MAX. Writing more than capacity inline bytes panics at the write.

pub fn finish(self) -> IoBufs

Freezes the inline buffer and assembles IoBufs by splitting it at the recorded push boundaries.

Trait Implementations

impl BufMut for Builder

fn remaining_mut(&self) -> usize

Returns the number of bytes that can be written from the current position until the end of the buffer is reached.

unsafe fn advance_mut(&mut self, cnt: usize)

Advance the internal cursor of the BufMut

fn chunk_mut(&mut self) -> &mut UninitSlice

Returns a mutable slice starting at the current BufMut position and of length between 0 and BufMut::remaining_mut(). Note that this can be shorter than the whole remainder of the buffer (this allows non-continuous implementation).

fn has_remaining_mut(&self) -> bool

Returns true if there is space in self for more bytes.

fn put<T>(&mut self, src: T)

where T: Buf, Self: Sized,

Transfer bytes into self from src and advance the cursor by the number of bytes written.

fn put_slice(&mut self, src: &[u8])

Transfer bytes into self from src and advance the cursor by the number of bytes written.

fn put_bytes(&mut self, val: u8, cnt: usize)

Put cnt bytes val into self.

fn put_u8(&mut self, n: u8)

Writes an unsigned 8 bit integer to self.

fn put_i8(&mut self, n: i8)

Writes a signed 8 bit integer to self.

fn put_u16(&mut self, n: u16)

Writes an unsigned 16 bit integer to self in big-endian byte order.

fn put_u16_le(&mut self, n: u16)

Writes an unsigned 16 bit integer to self in little-endian byte order.

fn put_u16_ne(&mut self, n: u16)

Writes an unsigned 16 bit integer to self in native-endian byte order.

fn put_i16(&mut self, n: i16)

Writes a signed 16 bit integer to self in big-endian byte order.

fn put_i16_le(&mut self, n: i16)

Writes a signed 16 bit integer to self in little-endian byte order.

fn put_i16_ne(&mut self, n: i16)

Writes a signed 16 bit integer to self in native-endian byte order.

fn put_u32(&mut self, n: u32)

Writes an unsigned 32 bit integer to self in big-endian byte order.

fn put_u32_le(&mut self, n: u32)

Writes an unsigned 32 bit integer to self in little-endian byte order.

fn put_u32_ne(&mut self, n: u32)

Writes an unsigned 32 bit integer to self in native-endian byte order.

fn put_i32(&mut self, n: i32)

Writes a signed 32 bit integer to self in big-endian byte order.

fn put_i32_le(&mut self, n: i32)

Writes a signed 32 bit integer to self in little-endian byte order.

fn put_i32_ne(&mut self, n: i32)

Writes a signed 32 bit integer to self in native-endian byte order.

fn put_u64(&mut self, n: u64)

Writes an unsigned 64 bit integer to self in the big-endian byte order.

fn put_u64_le(&mut self, n: u64)

Writes an unsigned 64 bit integer to self in little-endian byte order.

fn put_u64_ne(&mut self, n: u64)

Writes an unsigned 64 bit integer to self in native-endian byte order.

fn put_i64(&mut self, n: i64)

Writes a signed 64 bit integer to self in the big-endian byte order.

fn put_i64_le(&mut self, n: i64)

Writes a signed 64 bit integer to self in little-endian byte order.

fn put_i64_ne(&mut self, n: i64)

Writes a signed 64 bit integer to self in native-endian byte order.

fn put_u128(&mut self, n: u128)

Writes an unsigned 128 bit integer to self in the big-endian byte order.

fn put_u128_le(&mut self, n: u128)

Writes an unsigned 128 bit integer to self in little-endian byte order.

fn put_u128_ne(&mut self, n: u128)

Writes an unsigned 128 bit integer to self in native-endian byte order.

fn put_i128(&mut self, n: i128)

Writes a signed 128 bit integer to self in the big-endian byte order.

fn put_i128_le(&mut self, n: i128)

Writes a signed 128 bit integer to self in little-endian byte order.

fn put_i128_ne(&mut self, n: i128)

Writes a signed 128 bit integer to self in native-endian byte order.

fn put_uint(&mut self, n: u64, nbytes: usize)

Writes an unsigned n-byte integer to self in big-endian byte order.

fn put_uint_le(&mut self, n: u64, nbytes: usize)

Writes an unsigned n-byte integer to self in the little-endian byte order.

fn put_uint_ne(&mut self, n: u64, nbytes: usize)

Writes an unsigned n-byte integer to self in the native-endian byte order.

fn put_int(&mut self, n: i64, nbytes: usize)

Writes low nbytes of a signed integer to self in big-endian byte order.

fn put_int_le(&mut self, n: i64, nbytes: usize)

Writes low nbytes of a signed integer to self in little-endian byte order.

fn put_int_ne(&mut self, n: i64, nbytes: usize)

Writes low nbytes of a signed integer to self in native-endian byte order.

fn put_f32(&mut self, n: f32)

Writes an IEEE754 single-precision (4 bytes) floating point number to self in big-endian byte order.

fn put_f32_le(&mut self, n: f32)

Writes an IEEE754 single-precision (4 bytes) floating point number to self in little-endian byte order.

fn put_f32_ne(&mut self, n: f32)

Writes an IEEE754 single-precision (4 bytes) floating point number to self in native-endian byte order.

fn put_f64(&mut self, n: f64)

Writes an IEEE754 double-precision (8 bytes) floating point number to self in big-endian byte order.

fn put_f64_le(&mut self, n: f64)

Writes an IEEE754 double-precision (8 bytes) floating point number to self in little-endian byte order.

fn put_f64_ne(&mut self, n: f64)

Writes an IEEE754 double-precision (8 bytes) floating point number to self in native-endian byte order.

fn limit(self, limit: usize) -> Limit<Self>

where Self: Sized,

Creates an adaptor which can write at most limit bytes to self.

fn writer(self) -> Writer<Self>

where Self: Sized,

Creates an adaptor which implements the Write trait for self.

fn chain_mut<U>(self, next: U) -> Chain<Self, U>

where U: BufMut, Self: Sized,

Creates an adapter which will chain this buffer with another.

impl BufsMut for Builder

fn push(&mut self, chunk: impl Into<Bytes> + 'static)

Appends a chunk instead of writing its contents inline into the destination buffer.