[−][src]Struct bytes::BytesMut
A unique reference to a contiguous slice of memory.
BytesMut
represents a unique view into a potentially shared memory region.
Given the uniqueness guarantee, owners of BytesMut
handles are able to
mutate the memory. It is similar to a Vec<u8>
but with less copies and
allocations.
For more detail, see Bytes.
Growth
One key difference from Vec<u8>
is that most operations do not
implicitly grow the buffer. This means that calling my_bytes.put("hello world");
could panic if my_bytes
does not have enough capacity. Before
writing to the buffer, ensure that there is enough remaining capacity by
calling my_bytes.remaining_mut()
. In general, avoiding calls to reserve
is preferable.
The only exception is extend
which implicitly reserves required capacity.
Examples
use bytes::{BytesMut, BufMut}; let mut buf = BytesMut::with_capacity(64); buf.put(b'h'); buf.put(b'e'); buf.put("llo"); assert_eq!(&buf[..], b"hello"); // Freeze the buffer so that it can be shared let a = buf.freeze(); // This does not allocate, instead `b` points to the same memory. let b = a.clone(); assert_eq!(&a[..], b"hello"); assert_eq!(&b[..], b"hello");
Methods
impl BytesMut
[src]
pub fn with_capacity(capacity: usize) -> BytesMut
[src]
Creates a new BytesMut
with the specified capacity.
The returned BytesMut
will be able to hold at least capacity
bytes
without reallocating. If capacity
is under 4 * size_of::<usize>() - 1
,
then BytesMut
will not allocate.
It is important to note that this function does not specify the length
of the returned BytesMut
, but only the capacity.
Examples
use bytes::{BytesMut, BufMut}; let mut bytes = BytesMut::with_capacity(64); // `bytes` contains no data, even though there is capacity assert_eq!(bytes.len(), 0); bytes.put(&b"hello world"[..]); assert_eq!(&bytes[..], b"hello world");
pub fn new() -> BytesMut
[src]
Creates a new BytesMut
with default capacity.
Resulting object has length 0 and unspecified capacity. This function does not allocate.
Examples
use bytes::{BytesMut, BufMut}; let mut bytes = BytesMut::new(); assert_eq!(0, bytes.len()); bytes.reserve(2); bytes.put_slice(b"xy"); assert_eq!(&b"xy"[..], &bytes[..]);
pub fn len(&self) -> usize
[src]
Returns the number of bytes contained in this BytesMut
.
Examples
use bytes::BytesMut; let b = BytesMut::from(&b"hello"[..]); assert_eq!(b.len(), 5);
pub fn is_empty(&self) -> bool
[src]
Returns true if the BytesMut
has a length of 0.
Examples
use bytes::BytesMut; let b = BytesMut::with_capacity(64); assert!(b.is_empty());
pub fn capacity(&self) -> usize
[src]
Returns the number of bytes the BytesMut
can hold without reallocating.
Examples
use bytes::BytesMut; let b = BytesMut::with_capacity(64); assert_eq!(b.capacity(), 64);
pub fn freeze(self) -> Bytes
[src]
Converts self
into an immutable Bytes
.
The conversion is zero cost and is used to indicate that the slice referenced by the handle will no longer be mutated. Once the conversion is done, the handle can be cloned and shared across threads.
Examples
use bytes::{BytesMut, BufMut}; use std::thread; let mut b = BytesMut::with_capacity(64); b.put("hello world"); let b1 = b.freeze(); let b2 = b1.clone(); let th = thread::spawn(move || { assert_eq!(&b1[..], b"hello world"); }); assert_eq!(&b2[..], b"hello world"); th.join().unwrap();
pub fn split_off(&mut self, at: usize) -> BytesMut
[src]
Splits the bytes into two at the given index.
Afterwards self
contains elements [0, at)
, and the returned
BytesMut
contains elements [at, capacity)
.
This is an O(1)
operation that just increases the reference count
and sets a few indices.
Examples
use bytes::BytesMut; let mut a = BytesMut::from(&b"hello world"[..]); let mut b = a.split_off(5); a[0] = b'j'; b[0] = b'!'; assert_eq!(&a[..], b"jello"); assert_eq!(&b[..], b"!world");
Panics
Panics if at > capacity
.
pub fn take(&mut self) -> BytesMut
[src]
Removes the bytes from the current view, returning them in a new
BytesMut
handle.
Afterwards, self
will be empty, but will retain any additional
capacity that it had before the operation. This is identical to
self.split_to(self.len())
.
This is an O(1)
operation that just increases the reference count and
sets a few indices.
Examples
use bytes::{BytesMut, BufMut}; let mut buf = BytesMut::with_capacity(1024); buf.put(&b"hello world"[..]); let other = buf.take(); assert!(buf.is_empty()); assert_eq!(1013, buf.capacity()); assert_eq!(other, b"hello world"[..]);
pub fn split_to(&mut self, at: usize) -> BytesMut
[src]
Splits the buffer into two at the given index.
Afterwards self
contains elements [at, len)
, and the returned BytesMut
contains elements [0, at)
.
This is an O(1)
operation that just increases the reference count and
sets a few indices.
Examples
use bytes::BytesMut; let mut a = BytesMut::from(&b"hello world"[..]); let mut b = a.split_to(5); a[0] = b'!'; b[0] = b'j'; assert_eq!(&a[..], b"!world"); assert_eq!(&b[..], b"jello");
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::BytesMut; let mut buf = BytesMut::from(&b"hello world"[..]); buf.truncate(5); assert_eq!(buf, b"hello"[..]);
pub fn advance(&mut self, cnt: usize)
[src]
Shortens the buffer, dropping the first cnt
bytes and keeping the
rest.
This is the same function as Buf::advance
, and in the next breaking
release of bytes
, this implementation will be removed in favor of
having BytesMut
implement Buf
.
Panics
This function panics if cnt
is greater than self.len()
pub fn clear(&mut self)
[src]
Clears the buffer, removing all data.
Examples
use bytes::BytesMut; let mut buf = BytesMut::from(&b"hello world"[..]); buf.clear(); assert!(buf.is_empty());
pub fn resize(&mut self, new_len: usize, value: u8)
[src]
Resizes the buffer so that len
is equal to new_len
.
If new_len
is greater than len
, the buffer is extended by the
difference with each additional byte set to value
. If new_len
is
less than len
, the buffer is simply truncated.
Examples
use bytes::BytesMut; let mut buf = BytesMut::new(); buf.resize(3, 0x1); assert_eq!(&buf[..], &[0x1, 0x1, 0x1]); buf.resize(2, 0x2); assert_eq!(&buf[..], &[0x1, 0x1]); buf.resize(4, 0x3); assert_eq!(&buf[..], &[0x1, 0x1, 0x3, 0x3]);
pub unsafe fn set_len(&mut self, len: usize)
[src]
Sets the length of the buffer.
This will explicitly set the size of the buffer without actually modifying the data, so it is up to the caller to ensure that the data has been initialized.
Examples
use bytes::BytesMut; let mut b = BytesMut::from(&b"hello world"[..]); unsafe { b.set_len(5); } assert_eq!(&b[..], b"hello"); unsafe { b.set_len(11); } assert_eq!(&b[..], b"hello world");
Panics
This method will panic if len
is out of bounds for the underlying
slice or if it comes after the end
of the configured window.
pub fn reserve(&mut self, additional: usize)
[src]
Reserves capacity for at least additional
more bytes to be inserted
into the given BytesMut
.
More than additional
bytes may be reserved in order to avoid frequent
reallocations. A call to reserve
may result in an allocation.
Before allocating new buffer space, the function will attempt to reclaim space in the existing buffer. If the current handle references a small view in the original buffer and all other handles have been dropped, and the requested capacity is less than or equal to the existing buffer's capacity, then the current view will be copied to the front of the buffer and the handle will take ownership of the full buffer.
Examples
In the following example, a new buffer is allocated.
use bytes::BytesMut; let mut buf = BytesMut::from(&b"hello"[..]); buf.reserve(64); assert!(buf.capacity() >= 69);
In the following example, the existing buffer is reclaimed.
use bytes::{BytesMut, BufMut}; let mut buf = BytesMut::with_capacity(128); buf.put(&[0; 64][..]); let ptr = buf.as_ptr(); let other = buf.take(); assert!(buf.is_empty()); assert_eq!(buf.capacity(), 64); drop(other); buf.reserve(128); assert_eq!(buf.capacity(), 128); assert_eq!(buf.as_ptr(), ptr);
Panics
Panics if the new capacity overflows usize
.
pub fn extend_from_slice(&mut self, extend: &[u8])
[src]
Appends given bytes to this object.
If this BytesMut
object has not enough capacity, it is resized first.
So unlike put_slice
operation, extend_from_slice
does not panic.
Examples
use bytes::BytesMut; let mut buf = BytesMut::with_capacity(0); buf.extend_from_slice(b"aaabbb"); buf.extend_from_slice(b"cccddd"); assert_eq!(b"aaabbbcccddd", &buf[..]);
pub fn unsplit(&mut self, other: BytesMut)
[src]
Combine splitted BytesMut objects back as contiguous.
If BytesMut
objects were not contiguous originally, they will be extended.
Examples
use bytes::BytesMut; let mut buf = BytesMut::with_capacity(64); buf.extend_from_slice(b"aaabbbcccddd"); let splitted = buf.split_off(6); assert_eq!(b"aaabbb", &buf[..]); assert_eq!(b"cccddd", &splitted[..]); buf.unsplit(splitted); assert_eq!(b"aaabbbcccddd", &buf[..]);
Trait Implementations
impl BufMut for BytesMut
[src]
fn remaining_mut(&self) -> usize
[src]
unsafe fn advance_mut(&mut self, cnt: usize)
[src]
unsafe fn bytes_mut(&mut self) -> &mut [u8]
[src]
fn put_slice(&mut self, src: &[u8])
[src]
fn put_u8(&mut self, n: u8)
[src]
fn put_i8(&mut self, n: i8)
[src]
fn has_remaining_mut(&self) -> bool
[src]
unsafe fn bytes_vec_mut<'a>(&'a mut self, dst: &mut [&'a mut IoVec]) -> usize
[src]
fn put<T: IntoBuf>(&mut self, src: T) where
Self: Sized,
[src]
Self: Sized,
fn put_u16_be(&mut self, n: u16)
[src]
fn put_u16_le(&mut self, n: u16)
[src]
fn put_i16_be(&mut self, n: i16)
[src]
fn put_i16_le(&mut self, n: i16)
[src]
fn put_u32_be(&mut self, n: u32)
[src]
fn put_u32_le(&mut self, n: u32)
[src]
fn put_i32_be(&mut self, n: i32)
[src]
fn put_i32_le(&mut self, n: i32)
[src]
fn put_u64_be(&mut self, n: u64)
[src]
fn put_u64_le(&mut self, n: u64)
[src]
fn put_i64_be(&mut self, n: i64)
[src]
fn put_i64_le(&mut self, n: i64)
[src]
fn put_uint_be(&mut self, n: u64, nbytes: usize)
[src]
fn put_uint_le(&mut self, n: u64, nbytes: usize)
[src]
fn put_int_be(&mut self, n: i64, nbytes: usize)
[src]
fn put_int_le(&mut self, n: i64, nbytes: usize)
[src]
fn put_f32_be(&mut self, n: f32)
[src]
fn put_f32_le(&mut self, n: f32)
[src]
fn put_f64_be(&mut self, n: f64)
[src]
fn put_f64_le(&mut self, n: f64)
[src]
fn by_ref(&mut self) -> &mut Self where
Self: Sized,
[src]
Self: Sized,
ⓘImportant traits for Writer<B>fn writer(self) -> Writer<Self> where
Self: Sized,
[src]
Self: Sized,
impl FromBuf for BytesMut
[src]
impl IntoBuf for BytesMut
[src]
type Buf = Cursor<Self>
The Buf
type that self
is being converted into
fn into_buf(self) -> Self::Buf
[src]
impl<'a> IntoBuf for &'a BytesMut
[src]
type Buf = Cursor<&'a BytesMut>
The Buf
type that self
is being converted into
fn into_buf(self) -> Self::Buf
[src]
impl Eq for BytesMut
[src]
impl AsMut<[u8]> for BytesMut
[src]
impl Default for BytesMut
[src]
impl Clone for BytesMut
[src]
impl AsRef<[u8]> for BytesMut
[src]
impl PartialOrd<BytesMut> for BytesMut
[src]
fn partial_cmp(&self, other: &BytesMut) -> Option<Ordering>
[src]
#[must_use]
fn lt(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]
fn le(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]
fn gt(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]
fn ge(&self, other: &Rhs) -> bool
1.0.0[src]
impl PartialOrd<[u8]> for BytesMut
[src]
fn partial_cmp(&self, other: &[u8]) -> Option<Ordering>
[src]
#[must_use]
fn lt(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]
fn le(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]
fn gt(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]
fn ge(&self, other: &Rhs) -> bool
1.0.0[src]
impl PartialOrd<BytesMut> for [u8]
[src]
fn partial_cmp(&self, other: &BytesMut) -> Option<Ordering>
[src]
#[must_use]
fn lt(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]
fn le(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]
fn gt(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]
fn ge(&self, other: &Rhs) -> bool
1.0.0[src]
impl PartialOrd<str> for BytesMut
[src]
fn partial_cmp(&self, other: &str) -> Option<Ordering>
[src]
#[must_use]
fn lt(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]
fn le(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]
fn gt(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]
fn ge(&self, other: &Rhs) -> bool
1.0.0[src]
impl PartialOrd<BytesMut> for str
[src]
fn partial_cmp(&self, other: &BytesMut) -> Option<Ordering>
[src]
#[must_use]
fn lt(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]
fn le(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]
fn gt(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]
fn ge(&self, other: &Rhs) -> bool
1.0.0[src]
impl PartialOrd<Vec<u8>> for BytesMut
[src]
fn partial_cmp(&self, other: &Vec<u8>) -> Option<Ordering>
[src]
#[must_use]
fn lt(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]
fn le(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]
fn gt(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]
fn ge(&self, other: &Rhs) -> bool
1.0.0[src]
impl PartialOrd<BytesMut> for Vec<u8>
[src]
fn partial_cmp(&self, other: &BytesMut) -> Option<Ordering>
[src]
#[must_use]
fn lt(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]
fn le(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]
fn gt(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]
fn ge(&self, other: &Rhs) -> bool
1.0.0[src]
impl PartialOrd<String> for BytesMut
[src]
fn partial_cmp(&self, other: &String) -> Option<Ordering>
[src]
#[must_use]
fn lt(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]
fn le(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]
fn gt(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]
fn ge(&self, other: &Rhs) -> bool
1.0.0[src]
impl PartialOrd<BytesMut> for String
[src]
fn partial_cmp(&self, other: &BytesMut) -> Option<Ordering>
[src]
#[must_use]
fn lt(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]
fn le(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]
fn gt(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]
fn ge(&self, other: &Rhs) -> bool
1.0.0[src]
impl<'a, T: ?Sized> PartialOrd<&'a T> for BytesMut where
BytesMut: PartialOrd<T>,
[src]
BytesMut: PartialOrd<T>,
fn partial_cmp(&self, other: &&'a T) -> Option<Ordering>
[src]
#[must_use]
fn lt(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]
fn le(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]
fn gt(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]
fn ge(&self, other: &Rhs) -> bool
1.0.0[src]
impl<'a> PartialOrd<BytesMut> for &'a [u8]
[src]
fn partial_cmp(&self, other: &BytesMut) -> Option<Ordering>
[src]
#[must_use]
fn lt(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]
fn le(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]
fn gt(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]
fn ge(&self, other: &Rhs) -> bool
1.0.0[src]
impl<'a> PartialOrd<BytesMut> for &'a str
[src]
fn partial_cmp(&self, other: &BytesMut) -> Option<Ordering>
[src]
#[must_use]
fn lt(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]
fn le(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]
fn gt(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]
fn ge(&self, other: &Rhs) -> bool
1.0.0[src]
impl Extend<u8> for BytesMut
[src]
fn extend<T>(&mut self, iter: T) where
T: IntoIterator<Item = u8>,
[src]
T: IntoIterator<Item = u8>,
impl<'a> Extend<&'a u8> for BytesMut
[src]
fn extend<T>(&mut self, iter: T) where
T: IntoIterator<Item = &'a u8>,
[src]
T: IntoIterator<Item = &'a u8>,
impl PartialEq<BytesMut> for BytesMut
[src]
impl PartialEq<[u8]> for BytesMut
[src]
impl PartialEq<BytesMut> for [u8]
[src]
impl PartialEq<str> for BytesMut
[src]
impl PartialEq<BytesMut> for str
[src]
impl PartialEq<Vec<u8>> for BytesMut
[src]
impl PartialEq<BytesMut> for Vec<u8>
[src]
impl PartialEq<String> for BytesMut
[src]
impl PartialEq<BytesMut> for String
[src]
impl<'a, T: ?Sized> PartialEq<&'a T> for BytesMut where
BytesMut: PartialEq<T>,
[src]
BytesMut: PartialEq<T>,
impl<'a> PartialEq<BytesMut> for &'a [u8]
[src]
impl<'a> PartialEq<BytesMut> for &'a str
[src]
impl PartialEq<BytesMut> for Bytes
[src]
impl PartialEq<Bytes> for BytesMut
[src]
impl Ord for BytesMut
[src]
fn cmp(&self, other: &BytesMut) -> Ordering
[src]
fn max(self, other: Self) -> Self
1.21.0[src]
fn min(self, other: Self) -> Self
1.21.0[src]
fn clamp(self, min: Self, max: Self) -> Self
[src]
impl IntoIterator for BytesMut
[src]
type Item = u8
The type of the elements being iterated over.
type IntoIter = Iter<Cursor<BytesMut>>
Which kind of iterator are we turning this into?
fn into_iter(self) -> Self::IntoIter
[src]
impl<'a> IntoIterator for &'a BytesMut
[src]
type Item = u8
The type of the elements being iterated over.
type IntoIter = Iter<Cursor<&'a BytesMut>>
Which kind of iterator are we turning this into?
fn into_iter(self) -> Self::IntoIter
[src]
impl From<BytesMut> for Bytes
[src]
impl From<Vec<u8>> for BytesMut
[src]
impl From<String> for BytesMut
[src]
impl<'a> From<&'a [u8]> for BytesMut
[src]
impl<'a> From<&'a str> for BytesMut
[src]
impl From<Bytes> for BytesMut
[src]
impl DerefMut for BytesMut
[src]
impl Hash for BytesMut
[src]
fn hash<H>(&self, state: &mut H) where
H: Hasher,
[src]
H: Hasher,
fn hash_slice<H>(data: &[Self], state: &mut H) where
H: Hasher,
1.3.0[src]
H: Hasher,
impl Deref for BytesMut
[src]
impl Debug for BytesMut
[src]
impl Write for BytesMut
[src]
fn write_str(&mut self, s: &str) -> Result
[src]
fn write_fmt(&mut self, args: Arguments) -> Result
[src]
fn write_char(&mut self, c: char) -> Result<(), Error>
1.1.0[src]
impl FromIterator<u8> for BytesMut
[src]
fn from_iter<T: IntoIterator<Item = u8>>(into_iter: T) -> Self
[src]
impl<'a> FromIterator<&'a u8> for BytesMut
[src]
fn from_iter<T: IntoIterator<Item = &'a u8>>(into_iter: T) -> Self
[src]
impl BorrowMut<[u8]> for BytesMut
[src]
fn borrow_mut(&mut self) -> &mut [u8]
[src]
impl Borrow<[u8]> for BytesMut
[src]
Auto Trait Implementations
impl Send for BytesMut
impl Unpin for BytesMut
impl Sync for BytesMut
impl UnwindSafe for BytesMut
impl RefUnwindSafe for BytesMut
Blanket Implementations
impl<T> ToOwned for T where
T: Clone,
[src]
T: Clone,
type Owned = T
The resulting type after obtaining ownership.
fn to_owned(&self) -> T
[src]
fn clone_into(&self, target: &mut T)
[src]
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<I> IntoIterator for I where
I: Iterator,
[src]
I: Iterator,
type Item = <I as Iterator>::Item
The type of the elements being iterated over.
type IntoIter = I
Which kind of iterator are we turning this into?
fn into_iter(self) -> I
[src]
impl<T> From<T> for 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.
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>,
type Error = <U as TryFrom<T>>::Error
The type returned in the event of a conversion error.
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
[src]
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,