[−][src]Struct bytes::Bytes
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]
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 AsRef<[u8]> for Bytes
[src]
impl Borrow<[u8]> 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 Clone for Bytes
[src]
impl Debug for Bytes
[src]
impl Default for Bytes
[src]
impl Deref for Bytes
[src]
impl Drop for Bytes
[src]
impl Eq for Bytes
[src]
impl From<&'static [u8]> for Bytes
[src]
impl From<&'static str> for Bytes
[src]
impl From<BytesMut> for Bytes
[src]
impl From<String> for Bytes
[src]
impl From<Vec<u8, Global>> for Bytes
[src]
impl FromIterator<u8> for Bytes
[src]
fn from_iter<T: IntoIterator<Item = u8>>(into_iter: T) -> Self
[src]
impl Hash for Bytes
[src]
fn hash<H>(&self, state: &mut H) where
H: Hasher,
[src]
H: Hasher,
pub fn hash_slice<H>(data: &[Self], state: &mut H) where
H: Hasher,
1.3.0[src]
H: Hasher,
impl IntoIterator for Bytes
[src]
type Item = u8
The type of the elements being iterated over.
type IntoIter = IntoIter<Bytes>
Which kind of iterator are we turning this into?
fn into_iter(self) -> Self::IntoIter
[src]
impl<'a> IntoIterator for &'a Bytes
[src]
type Item = &'a u8
The type of the elements being iterated over.
type IntoIter = Iter<'a, u8>
Which kind of iterator are we turning this into?
fn into_iter(self) -> Self::IntoIter
[src]
impl LowerHex for Bytes
[src]
impl Ord for Bytes
[src]
fn cmp(&self, other: &Bytes) -> Ordering
[src]
#[must_use]pub fn max(self, other: Self) -> Self
1.21.0[src]
#[must_use]pub fn min(self, other: Self) -> Self
1.21.0[src]
#[must_use]pub fn clamp(self, min: Self, max: Self) -> Self
1.50.0[src]
impl<'a, T: ?Sized> PartialEq<&'a T> for Bytes where
Bytes: PartialEq<T>,
[src]
Bytes: PartialEq<T>,
impl PartialEq<[u8]> for Bytes
[src]
impl PartialEq<Bytes> for Bytes
[src]
impl PartialEq<Bytes> for [u8]
[src]
impl PartialEq<Bytes> for str
[src]
impl PartialEq<Bytes> for Vec<u8>
[src]
impl PartialEq<Bytes> for String
[src]
impl PartialEq<Bytes> for &[u8]
[src]
impl PartialEq<Bytes> for &str
[src]
impl PartialEq<Bytes> for BytesMut
[src]
impl PartialEq<BytesMut> for Bytes
[src]
fn eq(&self, other: &BytesMut) -> bool
[src]
#[must_use]pub fn ne(&self, other: &Rhs) -> bool
1.0.0[src]
impl PartialEq<String> for Bytes
[src]
impl PartialEq<Vec<u8, Global>> for Bytes
[src]
fn eq(&self, other: &Vec<u8>) -> bool
[src]
#[must_use]pub fn ne(&self, other: &Rhs) -> bool
1.0.0[src]
impl PartialEq<str> for Bytes
[src]
impl<'a, T: ?Sized> PartialOrd<&'a T> for Bytes where
Bytes: PartialOrd<T>,
[src]
Bytes: PartialOrd<T>,
fn partial_cmp(&self, other: &&'a T) -> Option<Ordering>
[src]
#[must_use]pub fn lt(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]pub fn le(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]pub fn gt(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]pub fn ge(&self, other: &Rhs) -> bool
1.0.0[src]
impl PartialOrd<[u8]> for Bytes
[src]
fn partial_cmp(&self, other: &[u8]) -> Option<Ordering>
[src]
#[must_use]pub fn lt(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]pub fn le(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]pub fn gt(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]pub fn ge(&self, other: &Rhs) -> bool
1.0.0[src]
impl PartialOrd<Bytes> for Bytes
[src]
fn partial_cmp(&self, other: &Bytes) -> Option<Ordering>
[src]
#[must_use]pub fn lt(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]pub fn le(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]pub fn gt(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]pub fn ge(&self, other: &Rhs) -> bool
1.0.0[src]
impl PartialOrd<Bytes> for [u8]
[src]
fn partial_cmp(&self, other: &Bytes) -> Option<Ordering>
[src]
#[must_use]pub fn lt(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]pub fn le(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]pub fn gt(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]pub fn ge(&self, other: &Rhs) -> bool
1.0.0[src]
impl PartialOrd<Bytes> for str
[src]
fn partial_cmp(&self, other: &Bytes) -> Option<Ordering>
[src]
#[must_use]pub fn lt(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]pub fn le(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]pub fn gt(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]pub fn ge(&self, other: &Rhs) -> bool
1.0.0[src]
impl PartialOrd<Bytes> for Vec<u8>
[src]
fn partial_cmp(&self, other: &Bytes) -> Option<Ordering>
[src]
#[must_use]pub fn lt(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]pub fn le(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]pub fn gt(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]pub fn ge(&self, other: &Rhs) -> bool
1.0.0[src]
impl PartialOrd<Bytes> for String
[src]
fn partial_cmp(&self, other: &Bytes) -> Option<Ordering>
[src]
#[must_use]pub fn lt(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]pub fn le(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]pub fn gt(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]pub fn ge(&self, other: &Rhs) -> bool
1.0.0[src]
impl PartialOrd<Bytes> for &[u8]
[src]
fn partial_cmp(&self, other: &Bytes) -> Option<Ordering>
[src]
#[must_use]pub fn lt(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]pub fn le(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]pub fn gt(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]pub fn ge(&self, other: &Rhs) -> bool
1.0.0[src]
impl PartialOrd<Bytes> for &str
[src]
fn partial_cmp(&self, other: &Bytes) -> Option<Ordering>
[src]
#[must_use]pub fn lt(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]pub fn le(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]pub fn gt(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]pub fn ge(&self, other: &Rhs) -> bool
1.0.0[src]
impl PartialOrd<String> for Bytes
[src]
fn partial_cmp(&self, other: &String) -> Option<Ordering>
[src]
#[must_use]pub fn lt(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]pub fn le(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]pub fn gt(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]pub fn ge(&self, other: &Rhs) -> bool
1.0.0[src]
impl PartialOrd<Vec<u8, Global>> for Bytes
[src]
fn partial_cmp(&self, other: &Vec<u8>) -> Option<Ordering>
[src]
#[must_use]pub fn lt(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]pub fn le(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]pub fn gt(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]pub fn ge(&self, other: &Rhs) -> bool
1.0.0[src]
impl PartialOrd<str> for Bytes
[src]
fn partial_cmp(&self, other: &str) -> Option<Ordering>
[src]
#[must_use]pub fn lt(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]pub fn le(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]pub fn gt(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]pub fn ge(&self, other: &Rhs) -> bool
1.0.0[src]
impl Send for Bytes
[src]
impl Sync for Bytes
[src]
impl UpperHex for Bytes
[src]
Auto Trait Implementations
Blanket Implementations
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
pub fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> From<T> for T
[src]
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T> ToOwned for T where
T: Clone,
[src]
T: Clone,
type Owned = T
The resulting type after obtaining ownership.
pub fn to_owned(&self) -> T
[src]
pub fn clone_into(&self, target: &mut T)
[src]
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,