tokio-rs/bytes
1
0
Fork 0
mirror of https://github.com/tokio-rs/bytes.git synced 2026-08-09 00:00:15 +02:00
Code Issues Packages Projects Releases Wiki Activity
Files
4462056e262ce9beef9d467eaabe76dd521f5a09
bytes/src/buf/buf_mut.rs
T

590 lines
15 KiB
Rust
Raw Blame History

use super::{Source, Writer};
use byteorder::ByteOrder;
use std::{cmp, io, ptr, usize};
/// 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");
/// ```
pub trait BufMut {
/// 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());
/// ```
fn remaining_mut(&self) -> 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 can panic if `cnt > self.remaining_mut()`.
unsafe fn advance_mut(&mut self, cnt: usize);
/// 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());
/// ```
fn has_remaining_mut(&self) -> bool {
self.remaining_mut() > 0
}
/// 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");
/// ```
unsafe fn bytes_mut(&mut self) -> &mut [u8];
/// 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<S: Source>(&mut self, src: S) where Self: Sized {
src.copy_to_buf(self);
}
/// 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_slice(&mut self, src: &[u8]) {
let mut off = 0;
assert!(self.remaining_mut() >= src.len(), "buffer overflow");
while off < src.len() {
let cnt;
unsafe {
let dst = self.bytes_mut();
cnt = cmp::min(dst.len(), src.len() - off);
ptr::copy_nonoverlapping(
src[off..].as_ptr(),
dst.as_mut_ptr(),
cnt);
off += cnt;
}
unsafe { self.advance_mut(cnt); }
}
}
/// 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_u16<T: ByteOrder>(&mut self, n: u16) {
let mut buf = [0; 2];
T::write_u16(&mut buf, n);
self.put_slice(&buf)
}
/// 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_i16<T: ByteOrder>(&mut self, n: i16) {
let mut buf = [0; 2];
T::write_i16(&mut buf, n);
self.put_slice(&buf)
}
/// 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_u32<T: ByteOrder>(&mut self, n: u32) {
let mut buf = [0; 4];
T::write_u32(&mut buf, n);
self.put_slice(&buf)
}
/// 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_i32<T: ByteOrder>(&mut self, n: i32) {
let mut buf = [0; 4];
T::write_i32(&mut buf, n);
self.put_slice(&buf)
}
/// 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_u64<T: ByteOrder>(&mut self, n: u64) {
let mut buf = [0; 8];
T::write_u64(&mut buf, n);
self.put_slice(&buf)
}
/// 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_i64<T: ByteOrder>(&mut self, n: i64) {
let mut buf = [0; 8];
T::write_i64(&mut buf, n);
self.put_slice(&buf)
}
/// 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_uint<T: ByteOrder>(&mut self, n: u64, nbytes: usize) {
let mut buf = [0; 8];
T::write_uint(&mut buf, n, nbytes);
self.put_slice(&buf[0..nbytes])
}
/// 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_int<T: ByteOrder>(&mut self, n: i64, nbytes: usize) {
let mut buf = [0; 8];
T::write_int(&mut buf, n, nbytes);
self.put_slice(&buf[0..nbytes])
}
/// 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_f32<T: ByteOrder>(&mut self, n: f32) {
let mut buf = [0; 4];
T::write_f32(&mut buf, n);
self.put_slice(&buf)
}
/// 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 put_f64<T: ByteOrder>(&mut self, n: f64) {
let mut buf = [0; 8];
T::write_f64(&mut buf, n);
self.put_slice(&buf)
}
/// 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 by_ref(&mut self) -> &mut Self where Self: Sized {
self
}
/// 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"[..]);
/// ```
fn writer(self) -> Writer<Self> where Self: Sized {
super::writer::new(self)
}
}
impl<'a, T: BufMut + ?Sized> BufMut for &'a mut T {
fn remaining_mut(&self) -> usize {
(**self).remaining_mut()
}
unsafe fn bytes_mut(&mut self) -> &mut [u8] {
(**self).bytes_mut()
}
unsafe fn advance_mut(&mut self, cnt: usize) {
(**self).advance_mut(cnt)
}
}
impl<T: BufMut + ?Sized> BufMut for Box<T> {
fn remaining_mut(&self) -> usize {
(**self).remaining_mut()
}
unsafe fn bytes_mut(&mut self) -> &mut [u8] {
(**self).bytes_mut()
}
unsafe fn advance_mut(&mut self, cnt: usize) {
(**self).advance_mut(cnt)
}
}
impl<T: AsMut<[u8]> + AsRef<[u8]>> BufMut for io::Cursor<T> {
fn remaining_mut(&self) -> usize {
use Buf;
self.remaining()
}
/// Advance the internal cursor of the BufMut
unsafe fn advance_mut(&mut self, cnt: usize) {
let pos = self.position() as usize;
let pos = cmp::min(self.get_mut().as_mut().len(), pos + cnt);
self.set_position(pos as u64);
}
/// Returns a mutable slice starting at the current BufMut position and of
/// length between 0 and `BufMut::remaining()`.
///
/// The returned byte slice may represent uninitialized memory.
unsafe fn bytes_mut(&mut self) -> &mut [u8] {
let pos = self.position() as usize;
&mut (self.get_mut().as_mut())[pos..]
}
}
impl BufMut for Vec<u8> {
fn remaining_mut(&self) -> usize {
usize::MAX - self.len()
}
unsafe fn advance_mut(&mut self, cnt: usize) {
let len = self.len() + cnt;
if len > self.capacity() {
// Reserve additional
// TODO: Should this case panic?
let cap = self.capacity();
self.reserve(cap - len);
}
self.set_len(len);
}
unsafe fn bytes_mut(&mut self) -> &mut [u8] {
use std::slice;
if self.capacity() == self.len() {
self.reserve(64); // Grow the vec
}
let cap = self.capacity();
let len = self.len();
let ptr = self.as_mut_ptr();
&mut slice::from_raw_parts_mut(ptr, cap)[len..]
}
}
Reference in New Issue View Git Blame Copy Permalink