[][src]Struct bytes::Bytes

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:

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]

impl Clone for Bytes[src]

impl Debug for Bytes[src]

impl Default for Bytes[src]

impl Deref for Bytes[src]

type Target = [u8]

The resulting type after dereferencing.

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]

impl Hash for Bytes[src]

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?

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?

impl LowerHex for Bytes[src]

impl Ord for Bytes[src]

impl<'a, T: ?Sized> PartialEq<&'a T> for Bytes where
    Bytes: PartialEq<T>, 
[src]

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]

impl PartialEq<String> for Bytes[src]

impl PartialEq<Vec<u8, Global>> for Bytes[src]

impl PartialEq<str> for Bytes[src]

impl<'a, T: ?Sized> PartialOrd<&'a T> for Bytes where
    Bytes: PartialOrd<T>, 
[src]

impl PartialOrd<[u8]> for Bytes[src]

impl PartialOrd<Bytes> for Bytes[src]

impl PartialOrd<Bytes> for [u8][src]

impl PartialOrd<Bytes> for str[src]

impl PartialOrd<Bytes> for Vec<u8>[src]

impl PartialOrd<Bytes> for String[src]

impl PartialOrd<Bytes> for &[u8][src]

impl PartialOrd<Bytes> for &str[src]

impl PartialOrd<String> for Bytes[src]

impl PartialOrd<Vec<u8, Global>> for Bytes[src]

impl PartialOrd<str> for Bytes[src]

impl Send for Bytes[src]

impl Sync for Bytes[src]

impl UpperHex for Bytes[src]

Auto Trait Implementations

impl RefUnwindSafe for Bytes[src]

impl Unpin for Bytes[src]

impl UnwindSafe for Bytes[src]

Blanket Implementations

impl<T> Any for T where
    T: 'static + ?Sized
[src]

impl<T> Borrow<T> for T where
    T: ?Sized
[src]

impl<T> BorrowMut<T> for T where
    T: ?Sized
[src]

impl<T> From<T> for T[src]

impl<T, U> Into<U> for T where
    U: From<T>, 
[src]

impl<T> ToOwned for T where
    T: Clone
[src]

type Owned = T

The resulting type after obtaining ownership.

impl<T, U> TryFrom<U> for T where
    U: Into<T>, 
[src]

type Error = Infallible

The type returned in the event of a conversion error.

impl<T, U> TryInto<U> for T where
    U: TryFrom<T>, 
[src]

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.