Trait bytes::BufMut
[−]
[src]
pub trait BufMut {
fn remaining_mut(&self) -> usize;
unsafe fn advance_mut(&mut self, cnt: usize);
unsafe fn bytes_mut(&mut self) -> &mut [u8];
fn has_remaining_mut(&self) -> bool { ... }
unsafe fn bytes_vec_mut<'a>(&'a mut self,
dst: &mut [&'a mut IoVec])
-> usize { ... }
fn put<T: IntoBuf>(&mut self, src: T) where Self: Sized { ... }
fn put_slice(&mut self, src: &[u8]) { ... }
fn put_u8(&mut self, n: u8) { ... }
fn put_i8(&mut self, n: i8) { ... }
fn put_u16<T: ByteOrder>(&mut self, n: u16) { ... }
fn put_i16<T: ByteOrder>(&mut self, n: i16) { ... }
fn put_u32<T: ByteOrder>(&mut self, n: u32) { ... }
fn put_i32<T: ByteOrder>(&mut self, n: i32) { ... }
fn put_u64<T: ByteOrder>(&mut self, n: u64) { ... }
fn put_i64<T: ByteOrder>(&mut self, n: i64) { ... }
fn put_uint<T: ByteOrder>(&mut self, n: u64, nbytes: usize) { ... }
fn put_int<T: ByteOrder>(&mut self, n: i64, nbytes: usize) { ... }
fn put_f32<T: ByteOrder>(&mut self, n: f32) { ... }
fn put_f64<T: ByteOrder>(&mut self, n: f64) { ... }
fn by_ref(&mut self) -> &mut Self where Self: Sized { ... }
fn writer(self) -> Writer<Self> where Self: Sized { ... }
}A trait for values that provide sequential write access to bytes.
Write bytes to a buffer
A buffer stores bytes in memory such that write operations are infallible.
The underlying storage may or may not be in contiguous memory. A BufMut
value is a cursor into the buffer. Writing to BufMut advances the cursor
position.
The simplest BufMut is a Vec<u8>.
use bytes::BufMut; let mut buf = vec![]; buf.put("hello world"); assert_eq!(buf, b"hello world");
Required Methods
fn remaining_mut(&self) -> usize
Returns the number of bytes that can be written from the current position until the end of the buffer is reached.
This value is greater than or equal to the length of the slice returned
by bytes_mut.
Examples
use bytes::BufMut; use std::io::Cursor; let mut dst = [0; 10]; let mut buf = Cursor::new(&mut dst[..]); assert_eq!(10, buf.remaining_mut()); buf.put("hello"); assert_eq!(5, buf.remaining_mut());
Implementer notes
Implementations of remaining_mut should ensure that the return value
does not change unless a call is made to advance_mut or any other
function that is documented to change the BufMut's current position.
unsafe fn advance_mut(&mut self, cnt: usize)
Advance the internal cursor of the BufMut
The next call to bytes_mut will return a slice starting cnt bytes
further into the underlying buffer.
This function is unsafe because there is no guarantee that the bytes being advanced to have been initialized.
Examples
use bytes::BufMut; let mut buf = Vec::with_capacity(16); unsafe { buf.bytes_mut()[0] = b'h'; buf.bytes_mut()[1] = b'e'; buf.advance_mut(2); buf.bytes_mut()[0] = b'l'; buf.bytes_mut()[1..3].copy_from_slice(b"lo"); buf.advance_mut(3); } assert_eq!(5, buf.len()); assert_eq!(buf, b"hello");
Panics
This function may panic if cnt > self.remaining_mut().
Implementer notes
It is recommended for implementations of advance_mut to panic if `cnt
self.remaining_mut()
. If the implementation does not panic, the call must behave as ifcnt == self.remaining_mut()`.
A call with cnt == 0 should never panic and be a no-op.
unsafe fn bytes_mut(&mut self) -> &mut [u8]
Returns a mutable slice starting at the current BufMut position and of
length between 0 and BufMut::remaining_mut().
This is a lower level function. Most operations are done with other functions.
The returned byte slice may represent uninitialized memory.
Examples
use bytes::BufMut; let mut buf = Vec::with_capacity(16); unsafe { buf.bytes_mut()[0] = b'h'; buf.bytes_mut()[1] = b'e'; buf.advance_mut(2); buf.bytes_mut()[0] = b'l'; buf.bytes_mut()[1..3].copy_from_slice(b"lo"); buf.advance_mut(3); } assert_eq!(5, buf.len()); assert_eq!(buf, b"hello");
Implementer notes
This function should never panic. Once the end of the buffer is reached,
i.e., BufMut::remaining_mut returns 0, calls to bytes_mut should
return an empty slice.
Provided Methods
fn has_remaining_mut(&self) -> bool
Returns true if there is space in self for more bytes.
This is equivalent to self.remaining_mut() != 0.
Examples
use bytes::BufMut; use std::io::Cursor; let mut dst = [0; 5]; let mut buf = Cursor::new(&mut dst); assert!(buf.has_remaining_mut()); buf.put("hello"); assert!(!buf.has_remaining_mut());
unsafe fn bytes_vec_mut<'a>(&'a mut self, dst: &mut [&'a mut IoVec]) -> usize
Fills dst with potentially multiple mutable slices starting at self's
current position.
If the BufMut is backed by disjoint slices of bytes, bytes_vec_mut
enables fetching more than one slice at once. dst is a slice of
mutable IoVec references, enabling the slice to be directly used with
readv without any further conversion. The sum of the lengths of all
the buffers in dst will be less than or equal to
Buf::remaining_mut().
The entries in dst will be overwritten, but the data contained by
the slices will not be modified. If bytes_vec_mut does not fill every
entry in dst, then dst is guaranteed to contain all remaining slices
in `self.
This is a lower level function. Most operations are done with other functions.
Implementer notes
This function should never panic. Once the end of the buffer is reached,
i.e., BufMut::remaining_mut returns 0, calls to bytes_vec_mut must
return 0 without mutating dst.
Implementations should also take care to properly handle being called
with dst being a zero length slice.
fn put<T: IntoBuf>(&mut self, src: T) where Self: Sized
Transfer bytes into self from src and advance the cursor by the
number of bytes written.
Examples
use bytes::BufMut; let mut buf = vec![]; buf.put(b'h'); buf.put(&b"ello"[..]); buf.put(" world"); assert_eq!(buf, b"hello world");
Panics
Panics if self does not have enough capacity to contain src.
fn put_slice(&mut self, src: &[u8])
Transfer bytes into self from src and advance the cursor by the
number of bytes written.
self must have enough remaining capacity to contain all of src.
use bytes::BufMut; use std::io::Cursor; let mut dst = [0; 6]; { let mut buf = Cursor::new(&mut dst); buf.put_slice(b"hello"); assert_eq!(1, buf.remaining_mut()); } assert_eq!(b"hello\0", &dst);
fn put_u8(&mut self, n: u8)
Writes an unsigned 8 bit integer to self.
The current position is advanced by 1.
Examples
use bytes::BufMut; let mut buf = vec![]; buf.put_u8(0x01); assert_eq!(buf, b"\x01");
Panics
This function panics if there is not enough remaining capacity in
self.
fn put_i8(&mut self, n: i8)
Writes a signed 8 bit integer to self.
The current position is advanced by 1.
Examples
use bytes::BufMut; let mut buf = vec![]; buf.put_i8(0x01); assert_eq!(buf, b"\x01");
Panics
This function panics if there is not enough remaining capacity in
self.
fn put_u16<T: ByteOrder>(&mut self, n: u16)
Writes an unsigned 16 bit integer to self in the specified byte order.
The current position is advanced by 2.
Examples
use bytes::{BufMut, BigEndian}; let mut buf = vec![]; buf.put_u16::<BigEndian>(0x0809); assert_eq!(buf, b"\x08\x09");
Panics
This function panics if there is not enough remaining capacity in
self.
fn put_i16<T: ByteOrder>(&mut self, n: i16)
Writes a signed 16 bit integer to self in the specified byte order.
The current position is advanced by 2.
Examples
use bytes::{BufMut, BigEndian}; let mut buf = vec![]; buf.put_i16::<BigEndian>(0x0809); assert_eq!(buf, b"\x08\x09");
Panics
This function panics if there is not enough remaining capacity in
self.
fn put_u32<T: ByteOrder>(&mut self, n: u32)
Writes an unsigned 32 bit integer to self in the specified byte order.
The current position is advanced by 4.
Examples
use bytes::{BufMut, BigEndian}; let mut buf = vec![]; buf.put_u32::<BigEndian>(0x0809A0A1); assert_eq!(buf, b"\x08\x09\xA0\xA1");
Panics
This function panics if there is not enough remaining capacity in
self.
fn put_i32<T: ByteOrder>(&mut self, n: i32)
Writes a signed 32 bit integer to self in the specified byte order.
The current position is advanced by 4.
Examples
use bytes::{BufMut, BigEndian}; let mut buf = vec![]; buf.put_i32::<BigEndian>(0x0809A0A1); assert_eq!(buf, b"\x08\x09\xA0\xA1");
Panics
This function panics if there is not enough remaining capacity in
self.
fn put_u64<T: ByteOrder>(&mut self, n: u64)
Writes an unsigned 64 bit integer to self in the specified byte order.
The current position is advanced by 8.
Examples
use bytes::{BufMut, BigEndian}; let mut buf = vec![]; buf.put_u64::<BigEndian>(0x0102030405060708); assert_eq!(buf, b"\x01\x02\x03\x04\x05\x06\x07\x08");
Panics
This function panics if there is not enough remaining capacity in
self.
fn put_i64<T: ByteOrder>(&mut self, n: i64)
Writes a signed 64 bit integer to self in the specified byte order.
The current position is advanced by 8.
Examples
use bytes::{BufMut, BigEndian}; let mut buf = vec![]; buf.put_i64::<BigEndian>(0x0102030405060708); assert_eq!(buf, b"\x01\x02\x03\x04\x05\x06\x07\x08");
Panics
This function panics if there is not enough remaining capacity in
self.
fn put_uint<T: ByteOrder>(&mut self, n: u64, nbytes: usize)
Writes an unsigned n-byte integer to self in the specified byte order.
The current position is advanced by nbytes.
Examples
use bytes::{BufMut, BigEndian}; let mut buf = vec![]; buf.put_uint::<BigEndian>(0x010203, 3); assert_eq!(buf, b"\x01\x02\x03");
Panics
This function panics if there is not enough remaining capacity in
self.
fn put_int<T: ByteOrder>(&mut self, n: i64, nbytes: usize)
Writes a signed n-byte integer to self in the specified byte order.
The current position is advanced by nbytes.
Examples
use bytes::{BufMut, BigEndian}; let mut buf = vec![]; buf.put_int::<BigEndian>(0x010203, 3); assert_eq!(buf, b"\x01\x02\x03");
Panics
This function panics if there is not enough remaining capacity in
self.
fn put_f32<T: ByteOrder>(&mut self, n: f32)
Writes an IEEE754 single-precision (4 bytes) floating point number to
self in the specified byte order.
The current position is advanced by 4.
Examples
use bytes::{BufMut, BigEndian}; let mut buf = vec![]; buf.put_f32::<BigEndian>(1.2f32); assert_eq!(buf, b"\x3F\x99\x99\x9A");
Panics
This function panics if there is not enough remaining capacity in
self.
fn put_f64<T: ByteOrder>(&mut self, n: f64)
Writes an IEEE754 double-precision (8 bytes) floating point number to
self in the specified byte order.
The current position is advanced by 8.
Examples
use bytes::{BufMut, BigEndian}; let mut buf = vec![]; buf.put_f64::<BigEndian>(1.2f64); assert_eq!(buf, b"\x3F\xF3\x33\x33\x33\x33\x33\x33");
Panics
This function panics if there is not enough remaining capacity in
self.
fn by_ref(&mut self) -> &mut Self where Self: Sized
Creates a "by reference" adaptor for this instance of BufMut.
The returned adapter also implements BufMut and will simply borrow
self.
Examples
use bytes::BufMut; use std::io; let mut buf = vec![]; { let mut reference = buf.by_ref(); // Adapt reference to `std::io::Write`. let mut writer = reference.writer(); // Use the buffer as a writter io::Write::write(&mut writer, &b"hello world"[..]).unwrap(); } // drop our &mut reference so that we can use `buf` again assert_eq!(buf, &b"hello world"[..]);
fn writer(self) -> Writer<Self> where Self: Sized
Creates an adaptor which implements the Write trait for self.
This function returns a new value which implements Write by adapting
the Write trait functions to the BufMut trait functions. Given that
BufMut operations are infallible, none of the Write functions will
return with Err.
Examples
use bytes::BufMut; use std::io::Write; let mut buf = vec![].writer(); let num = buf.write(&b"hello world"[..]).unwrap(); assert_eq!(11, num); let buf = buf.into_inner(); assert_eq!(*buf, b"hello world"[..]);