Struct bytes::Bytes [−][src]
pub struct Bytes { /* fields omitted */ }A cheaply cloneable and sliceable chunk of contiguous memory.
Bytes is an efficient container for storing and operating on contiguous
slices of memory. It is intended for use primarily in networking code, but
could have applications elsewhere as well.
Bytes values facilitate zero-copy network programming by allowing multiple
Bytes objects to point to the same underlying memory.
Bytes does not have a single implementation. It is an interface, whose
exact behavior is implemented through dynamic dispatch in several underlying
implementations of Bytes.
All Bytes implementations must fulfill the following requirements:
- They are cheaply cloneable and thereby shareable between an unlimited amount of components, for example by modifying a reference count.
- Instances can be sliced to refer to a subset of the the original buffer.
use bytes::Bytes; let mut mem = Bytes::from("Hello world"); let a = mem.slice(0..5); assert_eq!(a, "Hello"); let b = mem.split_to(6); assert_eq!(mem, "world"); assert_eq!(b, "Hello ");
Memory layout
The Bytes struct itself is fairly small, limited to 4 usize fields used
to track information about which segment of the underlying memory the
Bytes handle has access to.
Bytes keeps both a pointer to the shared state containing the full memory
slice and a pointer to the start of the region visible by the handle.
Bytes also tracks the length of its view into the memory.
Sharing
Bytes contains a vtable, which allows implementations of Bytes to define
how sharing/cloneing is implemented in detail.
When Bytes::clone() is called, Bytes will call the vtable function for
cloning the backing storage in order to share it behind between multiple
Bytes instances.
For Bytes implementations which refer to constant memory (e.g. created
via Bytes::from_static()) the cloning implementation will be a no-op.
For Bytes implementations which point to a reference counted shared storage
(e.g. an Arc<[u8]>), sharing will be implemented by increasing the
the reference count.
Due to this mechanism, multiple Bytes instances may point to the same
shared memory region.
Each Bytes instance can point to different sections within that
memory region, and Bytes instances may or may not have overlapping views
into the memory.
The following diagram visualizes a scenario where 2 Bytes instances make
use of an Arc-based backing storage, and provide access to different views:
Arc ptrs +---------+
________________________ / | Bytes 2 |
/ +---------+
/ +-----------+ | |
|_________/ | Bytes 1 | | |
| +-----------+ | |
| | | ___/ data | tail
| data | tail |/ |
v v v v
+-----+---------------------------------+-----+
| Arc | | | | |
+-----+---------------------------------+-----+
Implementations
impl Bytes[src]
impl Bytes[src]pub const fn new() -> Bytes[src]
Creates a new empty Bytes.
This will not allocate and the returned Bytes handle will be empty.
Examples
use bytes::Bytes; let b = Bytes::new(); assert_eq!(&b[..], b"");
pub const fn from_static(bytes: &'static [u8]) -> Bytes[src]
Creates a new Bytes from a static slice.
The returned Bytes will point directly to the static slice. There is
no allocating or copying.
Examples
use bytes::Bytes; let b = Bytes::from_static(b"hello"); assert_eq!(&b[..], b"hello");
pub fn len(&self) -> usize[src]
Returns the number of bytes contained in this Bytes.
Examples
use bytes::Bytes; let b = Bytes::from(&b"hello"[..]); assert_eq!(b.len(), 5);
pub fn is_empty(&self) -> bool[src]
Returns true if the Bytes has a length of 0.
Examples
use bytes::Bytes; let b = Bytes::new(); assert!(b.is_empty());
pub fn copy_from_slice(data: &[u8]) -> Self[src]
Creates Bytes instance from slice, by copying it.
pub fn slice(&self, range: impl RangeBounds<usize>) -> Bytes[src]
Returns a slice of self for the provided range.
This will increment the reference count for the underlying memory and
return a new Bytes handle set to the slice.
This operation is O(1).
Examples
use bytes::Bytes; let a = Bytes::from(&b"hello world"[..]); let b = a.slice(2..5); assert_eq!(&b[..], b"llo");
Panics
Requires that begin <= end and end <= self.len(), otherwise slicing
will panic.
pub fn slice_ref(&self, subset: &[u8]) -> Bytes[src]
Returns a slice of self that is equivalent to the given subset.
When processing a Bytes buffer with other tools, one often gets a
&[u8] which is in fact a slice of the Bytes, i.e. a subset of it.
This function turns that &[u8] into another Bytes, as if one had
called self.slice() with the offsets that correspond to subset.
This operation is O(1).
Examples
use bytes::Bytes; let bytes = Bytes::from(&b"012345678"[..]); let as_slice = bytes.as_ref(); let subset = &as_slice[2..6]; let subslice = bytes.slice_ref(&subset); assert_eq!(&subslice[..], b"2345");
Panics
Requires that the given sub slice is in fact contained within the
Bytes buffer; otherwise this function will panic.
#[must_use = "consider Bytes::truncate if you don't need the other half"]pub fn split_off(&mut self, at: usize) -> Bytes[src]
Splits the bytes into two at the given index.
Afterwards self contains elements [0, at), and the returned Bytes
contains elements [at, len).
This is an O(1) operation that just increases the reference count and
sets a few indices.
Examples
use bytes::Bytes; let mut a = Bytes::from(&b"hello world"[..]); let b = a.split_off(5); assert_eq!(&a[..], b"hello"); assert_eq!(&b[..], b" world");
Panics
Panics if at > len.
#[must_use = "consider Bytes::advance if you don't need the other half"]pub fn split_to(&mut self, at: usize) -> Bytes[src]
Splits the bytes into two at the given index.
Afterwards self contains elements [at, len), and the returned
Bytes contains elements [0, at).
This is an O(1) operation that just increases the reference count and
sets a few indices.
Examples
use bytes::Bytes; let mut a = Bytes::from(&b"hello world"[..]); let b = a.split_to(5); assert_eq!(&a[..], b" world"); assert_eq!(&b[..], b"hello");
Panics
Panics if at > len.
pub fn truncate(&mut self, len: usize)[src]
Shortens the buffer, keeping the first len bytes and dropping the
rest.
If len is greater than the buffer’s current length, this has no
effect.
The split_off method can emulate truncate, but this causes the
excess bytes to be returned instead of dropped.
Examples
use bytes::Bytes; let mut buf = Bytes::from(&b"hello world"[..]); buf.truncate(5); assert_eq!(buf, b"hello"[..]);
pub fn clear(&mut self)[src]
Clears the buffer, removing all data.
Examples
use bytes::Bytes; let mut buf = Bytes::from(&b"hello world"[..]); buf.clear(); assert!(buf.is_empty());
Trait Implementations
impl Buf for Bytes[src]
impl Buf for Bytes[src]fn remaining(&self) -> usize[src]
fn chunk(&self) -> &[u8][src]
fn advance(&mut self, cnt: usize)[src]
fn copy_to_bytes(&mut self, len: usize) -> Bytes[src]
fn chunks_vectored<'a>(&'a self, dst: &mut [IoSlice<'a>]) -> usize[src]
fn has_remaining(&self) -> bool[src]
fn copy_to_slice(&mut self, dst: &mut [u8])[src]
fn get_u8(&mut self) -> u8[src]
fn get_i8(&mut self) -> i8[src]
fn get_u16(&mut self) -> u16[src]
fn get_u16_le(&mut self) -> u16[src]
fn get_i16(&mut self) -> i16[src]
fn get_i16_le(&mut self) -> i16[src]
fn get_u32(&mut self) -> u32[src]
fn get_u32_le(&mut self) -> u32[src]
fn get_i32(&mut self) -> i32[src]
fn get_i32_le(&mut self) -> i32[src]
fn get_u64(&mut self) -> u64[src]
fn get_u64_le(&mut self) -> u64[src]
fn get_i64(&mut self) -> i64[src]
fn get_i64_le(&mut self) -> i64[src]
fn get_u128(&mut self) -> u128[src]
fn get_u128_le(&mut self) -> u128[src]
fn get_i128(&mut self) -> i128[src]
fn get_i128_le(&mut self) -> i128[src]
fn get_uint(&mut self, nbytes: usize) -> u64[src]
fn get_uint_le(&mut self, nbytes: usize) -> u64[src]
fn get_int(&mut self, nbytes: usize) -> i64[src]
fn get_int_le(&mut self, nbytes: usize) -> i64[src]
fn get_f32(&mut self) -> f32[src]
fn get_f32_le(&mut self) -> f32[src]
fn get_f64(&mut self) -> f64[src]
fn get_f64_le(&mut self) -> f64[src]
fn take(self, limit: usize) -> Take<Self> where
Self: Sized, [src]
Self: Sized,
fn chain<U: Buf>(self, next: U) -> Chain<Self, U> where
Self: Sized, [src]
Self: Sized,
fn reader(self) -> Reader<Self>ⓘ where
Self: Sized, [src]
Self: Sized,
impl FromIterator<u8> for Bytes[src]
impl FromIterator<u8> for Bytes[src]fn from_iter<T: IntoIterator<Item = u8>>(into_iter: T) -> Self[src]
impl IntoIterator for Bytes[src]
impl IntoIterator for Bytes[src]impl<'a> IntoIterator for &'a Bytes[src]
impl<'a> IntoIterator for &'a Bytes[src]impl<'a, T: ?Sized> PartialOrd<&'a T> for Bytes where
Bytes: PartialOrd<T>, [src]
impl<'a, T: ?Sized> PartialOrd<&'a T> for Bytes where
Bytes: PartialOrd<T>, [src]impl PartialOrd<Bytes> for Bytes[src]
impl PartialOrd<Bytes> for Bytes[src]impl PartialOrd<Bytes> for str[src]
impl PartialOrd<Bytes> for str[src]impl PartialOrd<Bytes> for Vec<u8>[src]
impl PartialOrd<Bytes> for Vec<u8>[src]impl PartialOrd<Bytes> for String[src]
impl PartialOrd<Bytes> for String[src]impl PartialOrd<Bytes> for &str[src]
impl PartialOrd<Bytes> for &str[src]impl PartialOrd<String> for Bytes[src]
impl PartialOrd<String> for Bytes[src]impl PartialOrd<str> for Bytes[src]
impl PartialOrd<str> for Bytes[src]