Struct BytesBuf 

pub struct BytesBuf { /* private fields */ }

Owns some memory capacity in which it allows you to place a sequence of bytes that you can thereafter extract as one or more BytesViews.

The capacity of the BytesBuf must be reserved in advance via reserve() before you can fill it with data.

Memory capacity

A single BytesBuf can use memory capacity from any memory provider, including a mix of different memory providers for the same BytesBuf instance. All methods that extend the memory capacity require the caller to provide a reference to the memory provider.

Conceptual design

The memory owned by a BytesBuf (its capacity) can be viewed as two regions:

• Filled memory - these bytes have been written to but have not yet been consumed as a BytesView. They may be inspected (via inspect()) or consumed (via consume()).
• Available memory - these bytes have not yet been written to and are available for writing via bytes::buf::BufMut or begin_vectored_write().

Existing BytesViews can be appended to the BytesBuf via append() without consuming capacity (each appended BytesView brings its own backing memory capacity).

Memory layout

A byte sequence backed by I/O memory may consist of any number of spans of consecutive bytes.

There is no upper or lower bound on the length of each span of bytes. At one extreme, the I/O subsystem may allocate a single span of memory to hold all the data. At the opposite extreme, it is legal for the I/O subsystem to create byte where byte is stored as a separate allocation. Higher level APIs are required not assume any specific block size

Examples of how b'Hello' may be stored in I/O memory:

• ['H', 'e', 'l', 'l', 'o']
• ['H', 'e'], ['l', 'l', 'o']
• ['H'], ['e'], ['l'], ['l'], ['o']

Implementations

impl BytesBuf

pub fn new() -> Self

Creates an instance with 0 bytes of capacity.

pub fn from_blocks<I>(blocks: I) -> Self

where I: IntoIterator<Item = Block>,

Creates an instance that takes exclusive ownership of the capacity in the provided memory blocks.

This is used by implementations of memory providers. To obtain a BytesBuf with available memory capacity, you need to use an implementation of Memory that provides you instances of BytesBuf.

There is no guarantee that the BytesBuf uses the blocks in the order provided to this function. Blocks may be used in any order.

pub fn reserve( &mut self, additional_bytes: usize, memory_provider: &impl Memory, )

Adds memory capacity to the sequence builder, ensuring there is enough capacity to accommodate additional_bytes of content in addition to existing content already present.

The requested reserve capacity may be extended further if the memory provider considers it more efficient to use a larger block of memory than strictly required for this operation.

pub fn append(&mut self, sequence: BytesView)

Appends the given sequence to the end of the sequence builder’s filled bytes region.

This automatically extends the builder’s capacity with the memory capacity used of the appended sequence, for a net zero change in remaining available capacity.

pub fn inspect(&self) -> BytesBufInspector<'_, '_>

Inspects the contents of the filled bytes region of the sequence builder. Typically used to identify whether and which contents may be consumed.

pub fn len(&self) -> usize

Length of the filled bytes region, ready to be consumed.

pub fn is_empty(&self) -> bool

Whether the filled bytes region is empty, i.e. contains no bytes that can be consumed.

This does not imply that the sequence builder has no remaining capacity.

pub fn capacity(&self) -> usize

The total capacity of the sequence builder.

This is the sum of the length of the filled bytes and the available bytes regions.

pub fn remaining_mut(&self) -> usize

How many more bytes can be written into the sequence builder before its memory capacity is exhausted.

pub fn consume(&mut self, len: usize) -> BytesView

Consumes len bytes from the beginning of the filled bytes region, returning a BytesView with those bytes.

Panics

Panics if the filled bytes region does not contain at least len bytes.

pub fn consume_checked(&mut self, len: usize) -> Option<BytesView>

Consumes len bytes from the beginning of the filled bytes region, returning a BytesView with those bytes.

Returns None if the filled bytes region does not contain at least len bytes.

pub fn consume_all(&mut self) -> BytesView

Consumes all filled bytes (if any), returning a BytesView with those bytes.

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

The first consecutive slice of memory that makes up the remaining capacity of the sequence builder.

After writing data to the start of this chunk, call advance_mut() to indicate how many bytes have been filled with data. The next call to chunk_mut() will return the next consecutive slice of memory you can fill.

pub unsafe fn advance_mut(&mut self, count: usize)

Advances the write head by count bytes, indicating that this many bytes from the start of chunk_mut() have been filled with data.

After this call, the indicated number of additional bytes may be consumed from the builder.

Panics

Panics if count is greater than the length of chunk_mut().

Safety

The caller must guarantee that the indicated number of bytes have been initialized with data, sequentially starting from the beginning of the chunk returned by chunk_mut().

pub fn begin_vectored_write( &mut self, max_len: Option<usize>, ) -> BytesBufVectoredWrite<'_>

Begins a vectored write operation that takes exclusive ownership of the sequence builder for the duration of the operation and allows individual slices of available capacity to be filled concurrently, up to an optional limit of max_len bytes.

Some I/O operations are naturally limited to a maximum number of bytes that can be transferred, so the length limit here allows us to project a restricted view of the available capacity to the caller without having to limit the true capacity of the builder.

Panics

Panics if max_len is greater than the remaining capacity of the sequence builder.

pub fn begin_vectored_write_checked( &mut self, max_len: Option<usize>, ) -> Option<BytesBufVectoredWrite<'_>>

Begins a vectored write operation that takes exclusive ownership of the sequence builder for the duration of the operation and allows individual slices of available capacity to be filled concurrently, up to an optional limit of max_len bytes.

Some I/O operations are naturally limited to a maximum number of bytes that can be transferred, so the length limit here allows us to project a restricted view of the available capacity to the caller without having to limit the true capacity of the builder.

Returns

Returns None if max_len is greater than the remaining capacity of the sequence builder.

pub fn extend_lifetime(&self) -> MemoryGuard

Creates a memory guard that extends the lifetime of the memory blocks that provide the backing memory capacity for this sequence builder.

This can be useful when unsafe code is used to reference the contents of a BytesBuf and it is possible to reach a condition where the BytesBuf itself no longer exists, even though the contents are referenced (e.g. because this is happening in non-Rust code).

pub fn as_write<M: Memory>(&mut self, memory: &M) -> impl Write

Exposes the instance through the Write trait.

The memory capacity of the BytesBuf will be automatically extended on demand with additional capacity from the supplied memory provider.

Trait Implementations

impl BufMut for BytesBuf

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 Debug for BytesBuf

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for BytesBuf

fn default() -> BytesBuf

Returns the “default value” for a type.

impl From<BytesView> for BytesBuf

fn from(value: BytesView) -> Self

Converts to this type from the input type.