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]