Struct IoBuf 

pub struct IoBuf { /* private fields */ }

Immutable byte buffer.

The handle stores the current readable pointer and length directly:

[ readable bytes .......... ]
^
ptr
len = readable bytes

Allocation ownership is represented by owner, a compact tagged pointer to an internal owner header. bytes::Buf methods use only ptr and len. Clone/drop/slice/split use owner on colder lifecycle paths.

Cloning and slicing are zero-copy. For pooled-backed values, the underlying allocation is returned to the pool when the final immutable reference is dropped.

All From<*> for IoBuf implementations are guaranteed to be non-copy conversions. Use IoBuf::copy_from_slice when an explicit copy from borrowed data is required.

Implementations

impl IoBuf

pub fn copy_from_slice(data: &[u8]) -> Self

Create a buffer by copying data from a slice.

Use this when you have a non-static &[u8] that needs owned storage. For static slices, prefer IoBuf::from which is zero-copy.

The copy lands in one native heap allocation with an inline owner header, so the result supports zero-copy IoBuf::try_into_mut.

pub fn is_pooled(&self) -> bool

Returns true if this buffer is tracked by a pool.

pub const fn len(&self) -> usize

Number of bytes remaining in the buffer.

pub const fn is_empty(&self) -> bool

Whether the buffer is empty.

pub const fn as_ptr(&self) -> *const u8

Get raw pointer to the first readable byte.

pub fn slice(&self, range: impl RangeBounds<usize>) -> Self

Returns a slice of self for the provided range (zero-copy).

Empty ranges return a detached empty buffer so pooled allocations are not pinned by empty views.

Panics

Panics if the range is out of bounds of the readable bytes, if its start is greater than its end, or if an inclusive bound overflows.

pub fn split_to(&mut self, at: usize) -> Self

Splits the buffer into two at the given index.

Afterwards self contains bytes [at, len), and the returned IoBuf contains bytes [0, at).

This is an O(1) zero-copy operation. Empty halves detach from the owner so pooled allocations are not pinned by empty views.

Panics

Panics if at > len.

pub fn try_into_mut(self) -> Result<IoBufMut, Self>

Try to convert this buffer into IoBufMut without copying.

Succeeds when this view is the unique owner of a native (heap, pooled, or adopted-vec) allocation, including uniquely-owned slices: capacity is recovered from the allocation base and the current view offset, so spare capacity beyond the view returns with it. Views with no owner (the default and detached empty views) convert trivially.

Declines for shared owners, non-empty static views, and external-backed views (Bytes cannot back a mutable handle). An empty view that still holds a shared or external owner declines like any other view.

pub fn into_mut_with_pool(self, pool: &BufferPool) -> IoBufMut

Convert this buffer into IoBufMut, allocating from pool if needed.

This is zero-copy when self has exclusive ownership of the backing storage. If the buffer is shared, this allocates a new buffer from pool and copies the readable bytes into it.

Trait Implementations

impl AsRef<[u8]> for IoBuf

fn as_ref(&self) -> &[u8]

Converts this type into a shared reference of the (usually inferred) input type.

impl Buf for IoBuf

fn copy_to_bytes(&mut self, len: usize) -> Bytes

Drains len readable bytes into Bytes.

Zero-copy despite the trait method’s name: a shared view is carved off and converted through the From<IoBuf> for Bytes fast paths.

fn remaining(&self) -> usize

Returns the number of bytes between the current position and the end of the buffer.

fn chunk(&self) -> &[u8]

Returns a slice starting at the current position and of length between 0 and Buf::remaining(). Note that this can return a shorter slice (this allows non-continuous internal representation).

fn advance(&mut self, cnt: usize)

Advance the internal cursor of the Buf

fn copy_to_slice(&mut self, dst: &mut [u8])

Copies bytes from self into dst.

fn try_copy_to_slice(&mut self, dst: &mut [u8]) -> Result<(), TryGetError>

Copies bytes from self into dst.

fn chunks_vectored<'a>(&'a self, dst: &mut [IoSlice<'a>]) -> usize

Fills dst with potentially multiple slices starting at self’s current position.

fn has_remaining(&self) -> bool

Returns true if there are any more bytes to consume

fn get_u8(&mut self) -> u8

Gets an unsigned 8 bit integer from self.

fn get_i8(&mut self) -> i8

Gets a signed 8 bit integer from self.

fn get_u16(&mut self) -> u16

Gets an unsigned 16 bit integer from self in big-endian byte order.

fn get_u16_le(&mut self) -> u16

Gets an unsigned 16 bit integer from self in little-endian byte order.

fn get_u16_ne(&mut self) -> u16

Gets an unsigned 16 bit integer from self in native-endian byte order.

fn get_i16(&mut self) -> i16

Gets a signed 16 bit integer from self in big-endian byte order.

fn get_i16_le(&mut self) -> i16

Gets a signed 16 bit integer from self in little-endian byte order.

fn get_i16_ne(&mut self) -> i16

Gets a signed 16 bit integer from self in native-endian byte order.

fn get_u32(&mut self) -> u32

Gets an unsigned 32 bit integer from self in the big-endian byte order.

fn get_u32_le(&mut self) -> u32

Gets an unsigned 32 bit integer from self in the little-endian byte order.

fn get_u32_ne(&mut self) -> u32

Gets an unsigned 32 bit integer from self in native-endian byte order.

fn get_i32(&mut self) -> i32

Gets a signed 32 bit integer from self in big-endian byte order.

fn get_i32_le(&mut self) -> i32

Gets a signed 32 bit integer from self in little-endian byte order.

fn get_i32_ne(&mut self) -> i32

Gets a signed 32 bit integer from self in native-endian byte order.

fn get_u64(&mut self) -> u64

Gets an unsigned 64 bit integer from self in big-endian byte order.

fn get_u64_le(&mut self) -> u64

Gets an unsigned 64 bit integer from self in little-endian byte order.

fn get_u64_ne(&mut self) -> u64

Gets an unsigned 64 bit integer from self in native-endian byte order.

fn get_i64(&mut self) -> i64

Gets a signed 64 bit integer from self in big-endian byte order.

fn get_i64_le(&mut self) -> i64

Gets a signed 64 bit integer from self in little-endian byte order.

fn get_i64_ne(&mut self) -> i64

Gets a signed 64 bit integer from self in native-endian byte order.

fn get_u128(&mut self) -> u128

Gets an unsigned 128 bit integer from self in big-endian byte order.

fn get_u128_le(&mut self) -> u128

Gets an unsigned 128 bit integer from self in little-endian byte order.

fn get_u128_ne(&mut self) -> u128

Gets an unsigned 128 bit integer from self in native-endian byte order.

fn get_i128(&mut self) -> i128

Gets a signed 128 bit integer from self in big-endian byte order.

fn get_i128_le(&mut self) -> i128

Gets a signed 128 bit integer from self in little-endian byte order.

fn get_i128_ne(&mut self) -> i128

Gets a signed 128 bit integer from self in native-endian byte order.

fn get_uint(&mut self, nbytes: usize) -> u64

Gets an unsigned n-byte integer from self in big-endian byte order.

fn get_uint_le(&mut self, nbytes: usize) -> u64

Gets an unsigned n-byte integer from self in little-endian byte order.

fn get_uint_ne(&mut self, nbytes: usize) -> u64

Gets an unsigned n-byte integer from self in native-endian byte order.

fn get_int(&mut self, nbytes: usize) -> i64

Gets a signed n-byte integer from self in big-endian byte order.

fn get_int_le(&mut self, nbytes: usize) -> i64

Gets a signed n-byte integer from self in little-endian byte order.

fn get_int_ne(&mut self, nbytes: usize) -> i64

Gets a signed n-byte integer from self in native-endian byte order.

fn get_f32(&mut self) -> f32

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

fn get_f32_le(&mut self) -> f32

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

fn get_f32_ne(&mut self) -> f32

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

fn get_f64(&mut self) -> f64

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

fn get_f64_le(&mut self) -> f64

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

fn get_f64_ne(&mut self) -> f64

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

fn try_get_u8(&mut self) -> Result<u8, TryGetError>

Gets an unsigned 8 bit integer from self.

fn try_get_i8(&mut self) -> Result<i8, TryGetError>

Gets a signed 8 bit integer from self.

fn try_get_u16(&mut self) -> Result<u16, TryGetError>

Gets an unsigned 16 bit integer from self in big-endian byte order.

fn try_get_u16_le(&mut self) -> Result<u16, TryGetError>

Gets an unsigned 16 bit integer from self in little-endian byte order.

fn try_get_u16_ne(&mut self) -> Result<u16, TryGetError>

Gets an unsigned 16 bit integer from self in native-endian byte order.

fn try_get_i16(&mut self) -> Result<i16, TryGetError>

Gets a signed 16 bit integer from self in big-endian byte order.

fn try_get_i16_le(&mut self) -> Result<i16, TryGetError>

Gets an signed 16 bit integer from self in little-endian byte order.

fn try_get_i16_ne(&mut self) -> Result<i16, TryGetError>

Gets a signed 16 bit integer from self in native-endian byte order.

fn try_get_u32(&mut self) -> Result<u32, TryGetError>

Gets an unsigned 32 bit integer from self in big-endian byte order.

fn try_get_u32_le(&mut self) -> Result<u32, TryGetError>

Gets an unsigned 32 bit integer from self in little-endian byte order.

fn try_get_u32_ne(&mut self) -> Result<u32, TryGetError>

Gets an unsigned 32 bit integer from self in native-endian byte order.

fn try_get_i32(&mut self) -> Result<i32, TryGetError>

Gets a signed 32 bit integer from self in big-endian byte order.

fn try_get_i32_le(&mut self) -> Result<i32, TryGetError>

Gets a signed 32 bit integer from self in little-endian byte order.

fn try_get_i32_ne(&mut self) -> Result<i32, TryGetError>

Gets a signed 32 bit integer from self in native-endian byte order.

fn try_get_u64(&mut self) -> Result<u64, TryGetError>

Gets an unsigned 64 bit integer from self in big-endian byte order.

fn try_get_u64_le(&mut self) -> Result<u64, TryGetError>

Gets an unsigned 64 bit integer from self in little-endian byte order.

fn try_get_u64_ne(&mut self) -> Result<u64, TryGetError>

Gets an unsigned 64 bit integer from self in native-endian byte order.

fn try_get_i64(&mut self) -> Result<i64, TryGetError>

Gets a signed 64 bit integer from self in big-endian byte order.

fn try_get_i64_le(&mut self) -> Result<i64, TryGetError>

Gets a signed 64 bit integer from self in little-endian byte order.

fn try_get_i64_ne(&mut self) -> Result<i64, TryGetError>

Gets a signed 64 bit integer from self in native-endian byte order.

fn try_get_u128(&mut self) -> Result<u128, TryGetError>

Gets an unsigned 128 bit integer from self in big-endian byte order.

fn try_get_u128_le(&mut self) -> Result<u128, TryGetError>

Gets an unsigned 128 bit integer from self in little-endian byte order.

fn try_get_u128_ne(&mut self) -> Result<u128, TryGetError>

Gets an unsigned 128 bit integer from self in native-endian byte order.

fn try_get_i128(&mut self) -> Result<i128, TryGetError>

Gets a signed 128 bit integer from self in big-endian byte order.

fn try_get_i128_le(&mut self) -> Result<i128, TryGetError>

Gets a signed 128 bit integer from self in little-endian byte order.

fn try_get_i128_ne(&mut self) -> Result<i128, TryGetError>

Gets a signed 128 bit integer from self in native-endian byte order.

fn try_get_uint(&mut self, nbytes: usize) -> Result<u64, TryGetError>

Gets an unsigned n-byte integer from self in big-endian byte order.

fn try_get_uint_le(&mut self, nbytes: usize) -> Result<u64, TryGetError>

Gets an unsigned n-byte integer from self in little-endian byte order.

fn try_get_uint_ne(&mut self, nbytes: usize) -> Result<u64, TryGetError>

Gets an unsigned n-byte integer from self in native-endian byte order.

fn try_get_int(&mut self, nbytes: usize) -> Result<i64, TryGetError>

Gets a signed n-byte integer from self in big-endian byte order.

fn try_get_int_le(&mut self, nbytes: usize) -> Result<i64, TryGetError>

Gets a signed n-byte integer from self in little-endian byte order.

fn try_get_int_ne(&mut self, nbytes: usize) -> Result<i64, TryGetError>

Gets a signed n-byte integer from self in native-endian byte order.

fn try_get_f32(&mut self) -> Result<f32, TryGetError>

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

fn try_get_f32_le(&mut self) -> Result<f32, TryGetError>

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

fn try_get_f32_ne(&mut self) -> Result<f32, TryGetError>

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

fn try_get_f64(&mut self) -> Result<f64, TryGetError>

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

fn try_get_f64_le(&mut self) -> Result<f64, TryGetError>

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

fn try_get_f64_ne(&mut self) -> Result<f64, TryGetError>

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

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

where Self: Sized,

Creates an adaptor which will read at most limit bytes from self.

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

where U: Buf, Self: Sized,

Creates an adaptor which will chain this buffer with another.

fn reader(self) -> Reader<Self>

where Self: Sized,

Creates an adaptor which implements the Read trait for self.

impl Clone for IoBuf

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for IoBuf

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

Formats the value using the given formatter.

impl Default for IoBuf

fn default() -> Self

Returns the “default value” for a type.

impl Drop for IoBuf

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl EncodeSize for IoBuf

fn encode_size(&self) -> usize

Returns the encoded size of this value (in bytes).

fn encode_inline_size(&self) -> usize

Returns the encoded size excluding bytes passed to BufsMut::push during Write::write_bufs. Used to size the working buffer for inline writes. Override alongside Write::write_bufs for types where large Bytes fields go via push; failing to do so will over-allocate.

impl Eq for IoBuf

impl<const N: usize> From<&'static [u8; N]> for IoBuf

Zero-copy: creates a static view with no owner.

fn from(array: &'static [u8; N]) -> Self

Converts to this type from the input type.

impl From<&'static [u8]> for IoBuf

Zero-copy: creates a static view with no owner.

fn from(slice: &'static [u8]) -> Self

Converts to this type from the input type.

impl From<Bytes> for IoBuf

Convert Bytes into an IoBuf without copying.

The Bytes value moves into a small external owner and the handle points directly into its payload. Handle clones and drops never touch the inner refcount. Only the final release and the slice_ref conversion fast paths do.

fn from(bytes: Bytes) -> Self

Converts to this type from the input type.

impl From<BytesMut> for IoBuf

Convert BytesMut into an IoBuf without copying (via freeze).

fn from(bytes: BytesMut) -> Self

Converts to this type from the input type.

impl From<IoBuf> for Vec<u8>

Convert an IoBuf into a Vec<u8>.

This conversion copies the readable bytes.

fn from(buf: IoBuf) -> Self

Converts to this type from the input type.

impl From<IoBuf> for Bytes

Convert an IoBuf into Bytes without copying readable data.

Static views convert via Bytes::from_static (free), external-backed views via Bytes::slice_ref on the inner Bytes (a refcount clone, though the first conversion of a still-promotable inner Bytes pays bytes’ one shared-header allocation), and native heap/pooled views via Bytes::from_owner (one box).

fn from(buf: IoBuf) -> Self

Converts to this type from the input type.

impl From<IoBuf> for IoBufMut

Zero-copy when exclusive ownership can be recovered (see IoBuf::try_into_mut), copies otherwise.

fn from(buf: IoBuf) -> Self

Converts to this type from the input type.

impl From<IoBuf> for IoBufs

Zero-copy: wraps the buffer as the single chunk.

fn from(buf: IoBuf) -> Self

Converts to this type from the input type.

impl From<Vec<u8>> for IoBuf

Convert a Vec<u8> into an IoBuf without copying.

Adopts the vec’s allocation when its spare capacity can host the owner header, and otherwise moves it into Bytes behind an external owner.

fn from(vec: Vec<u8>) -> Self

Converts to this type from the input type.

impl PartialEq for IoBuf

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl<const N: usize> PartialEq<&[u8; N]> for IoBuf

fn eq(&self, other: &&[u8; N]) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl PartialEq<&[u8]> for IoBuf

fn eq(&self, other: &&[u8]) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl<const N: usize> PartialEq<[u8; N]> for IoBuf

fn eq(&self, other: &[u8; N]) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl PartialEq<[u8]> for IoBuf

fn eq(&self, other: &[u8]) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Read for IoBuf

type Cfg = RangeCfg<usize>

The Cfg type parameter allows passing configuration during the read process. This is crucial for safely decoding untrusted data, for example, by providing size limits for collections or strings.

fn read_cfg(buf: &mut impl Buf, range: &Self::Cfg) -> Result<Self, Error>

Reads a value from the buffer using the provided configuration cfg.

impl Send for IoBuf

impl Sync for IoBuf

impl Write for IoBuf

fn write(&self, buf: &mut impl BufMut)

Writes the binary representation of self to the provided buffer buf.

fn write_bufs(&self, buf: &mut impl BufsMut)

Writes to a BufsMut, allowing existing Bytes chunks to be appended via BufsMut::push instead of written inline. Must encode to the same format as Write::write. Defaults to Write::write.