Struct BytesView 

pub struct BytesView { /* private fields */ }

A sequence of immutable bytes that can be inspected and consumed.

Note that only the contents of a sequence are immutable - the sequence itself can be mutated in terms of progressively marking its contents as consumed until it becomes empty. The typical mechanism for consuming the contents of a BytesView is the bytes::buf::Buf trait that it implements.

To create a BytesView, use a BytesBuf or clone/slice an existing BytesView.

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 BytesView

pub const fn new() -> Self

Returns an empty sequence.

Use a BytesBuf to create a sequence that contains data.

pub fn from_sequences<I>(sequences: I) -> Self

where I: IntoIterator<Item = Self>, <I as IntoIterator>::IntoIter: DoubleEndedIterator,

Concatenates a number of existing sequences, yielding a combined view.

Later changes made to the input sequences will not be reflected in the output sequence.

pub fn copied_from_slice(bytes: &[u8], memory_provider: &impl Memory) -> Self

Shorthand to copy a byte slice into a new BytesView, which is a common operation.

pub fn len(&self) -> usize

The number of bytes remaining in the sequence.

pub fn is_empty(&self) -> bool

Whether the sequence is empty.

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.

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

pub fn slice<R>(&self, range: R) -> Self

where R: RangeBounds<usize>,

Returns a sub-sequence of the sequence without consuming any data in the original.

The bounds logic only considers data currently present in the sequence. Any data already consumed is not considered part of the sequence.

Panics

Panics if the provided range is outside the bounds of the sequence.

pub fn slice_checked<R>(&self, range: R) -> Option<Self>

where R: RangeBounds<usize>,

Returns a sub-sequence of the sequence without consuming any data in the original, or None if the range is outside the bounds of the sequence.

The bounds logic only considers data currently present in the sequence. Any data already consumed is not considered part of the sequence.

pub fn consume_all_chunks<F>(&mut self, f: F)

where F: FnMut(&[u8]),

Executes a function f on each chunk in the sequence, in order, and marks the entire sequence as consumed.

pub fn into_bytes(self) -> Bytes

Consumes the sequence and returns an instance of Bytes.

We do not expose From<BytesView> for Bytes because this is not guaranteed to be a cheap operation and may involve data copying, so .into_bytes() must be explicitly called to make the conversion obvious.

Performance

This operation is zero-copy if the sequence is backed by a single consecutive span of memory.

If the sequence is backed by multiple spans of memory, the data will be copied to a new Bytes instance backed by memory capacity from the Rust global allocator.

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

Returns the first consecutive chunk of bytes in the byte sequence.

There are no guarantees on the length of each chunk. In a non-empty sequence, each chunk may contain anywhere between 1 byte and all bytes of the sequence.

Returns an empty slice if the sequence is empty.

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

Fills an array of IoSlice with chunks from the start of the sequence.

See also chunks_as_slices_vectored() for a version that fills an array of slices instead of IoSlice.

pub fn chunks_as_slices_vectored<'a>(&'a self, dst: &mut [&'a [u8]]) -> usize

Fills an array of slices with chunks from the start of the sequence.

This is equivalent to chunks_vectored() but as regular slices, without the IoSlice wrapper, which can be unnecessary/limiting and is not always desirable.

pub fn chunk_meta(&self) -> Option<&dyn Any>

Inspects the metadata of the current chunk of memory referenced by chunk().

None if there is no metadata associated with the chunk or if the sequence is empty.

pub fn iter_chunk_metas(&self) -> BytesViewChunkMetasIterator<'_>

Iterates over the metadata of all the chunks in the sequence.

A chunk is any consecutive span of memory that would be returned by chunk() at some point during the consumption of a BytesView.

You may wish to iterate over the metadata to determine in advance which implementation strategy to use for a function, depending on what the metadata indicates about the configuration of the memory blocks backing the byte sequence.

pub fn advance(&mut self, count: usize)

Marks the first count bytes of the sequence as consumed, dropping them from the sequence.

Panics

Panics if count is greater than the number of bytes remaining in the sequence.

pub fn append(&mut self, other: Self)

Appends another byte sequence to the end of this one.

Panics

Panics if the resulting sequence would be larger than usize::MAX bytes.

pub fn concat(&self, other: Self) -> Self

Returns a new byte sequence that concatenates this byte sequence with another.

Panics

Panics if the resulting sequence would be larger than usize::MAX bytes.

Trait Implementations

impl Buf for BytesView

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 chunks_vectored<'a>(&'a self, dst: &mut [IoSlice<'a>]) -> usize

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

fn advance(&mut self, cnt: usize)

Advance the internal cursor of the Buf

fn has_remaining(&self) -> bool

Returns true if there are any more bytes to consume

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

Copies bytes from self into dst.

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_copy_to_slice(&mut self, dst: &mut [u8]) -> Result<(), TryGetError>

Copies bytes from self into dst.

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 copy_to_bytes(&mut self, len: usize) -> Bytes

Consumes len bytes inside self and returns new instance of Bytes with this data.

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 BytesView

fn clone(&self) -> BytesView

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for BytesView

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

Formats the value using the given formatter.

impl Default for BytesView

fn default() -> Self

Returns the “default value” for a type.

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

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

Converts to this type from the input type.

impl<const LEN: usize> From<&'static [u8; LEN]> for BytesView

fn from(value: &'static [u8; LEN]) -> Self

Converts to this type from the input type.

impl From<Bytes> for BytesView

fn from(value: Bytes) -> Self

Converts a Bytes instance into a BytesView.

impl From<BytesView> for BytesBuf

fn from(value: BytesView) -> Self

Converts to this type from the input type.

impl From<Vec<u8>> for BytesView

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

Converts to this type from the input type.

impl PartialEq<&[u8]> for BytesView

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<const LEN: usize> PartialEq<&[u8; LEN]> for BytesView

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<BytesView> for &[u8]

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<const LEN: usize> PartialEq<BytesView> for &[u8; LEN]

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq for BytesView

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.