mirror of
https://github.com/openharmony/third_party_rust_bytes.git
synced 2026-07-22 04:45:27 -04:00
More docs
This commit is contained in:
Carl Lerche
+615
-75
@@ -4,9 +4,10 @@ use std::{cmp, io, ptr, usize};
|
||||
|
||||
/// Read bytes from a buffer.
|
||||
///
|
||||
/// A buffer stores bytes in memory such that read access is infallible. The
|
||||
/// underlying storage may or may not be in contiguous memory. A `Buf` value is
|
||||
/// a cursor into the buffer. Reading from `Buf` advances the cursor position.
|
||||
/// A buffer stores bytes in memory such that read operations are infallible.
|
||||
/// The underlying storage may or may not be in contiguous memory. A `Buf` value
|
||||
/// is a cursor into the buffer. Reading from `Buf` advances the cursor
|
||||
/// position.
|
||||
///
|
||||
/// The simplest `Buf` is a `Cursor` wrapping a `[u8]`.
|
||||
///
|
||||
@@ -35,10 +36,10 @@ pub trait Buf {
|
||||
/// # Examples
|
||||
///
|
||||
/// ```
|
||||
/// use bytes::{Bytes, Buf, IntoBuf};
|
||||
/// use bytes::Buf;
|
||||
/// use std::io::Cursor;
|
||||
///
|
||||
/// let bytes = Bytes::from("hello world");
|
||||
/// let mut buf = bytes.into_buf();
|
||||
/// let mut buf = Cursor::new(b"hello world");
|
||||
///
|
||||
/// assert_eq!(buf.remaining(), 11);
|
||||
///
|
||||
@@ -57,10 +58,10 @@ pub trait Buf {
|
||||
/// # Examples
|
||||
///
|
||||
/// ```
|
||||
/// use bytes::{Bytes, Buf, IntoBuf};
|
||||
/// use bytes::Buf;
|
||||
/// use std::io::Cursor;
|
||||
///
|
||||
/// let bytes = Bytes::from("hello world");
|
||||
/// let mut buf = bytes.into_buf();
|
||||
/// let mut buf = Cursor::new(b"hello world");
|
||||
///
|
||||
/// assert_eq!(buf.bytes(), b"hello world");
|
||||
///
|
||||
@@ -78,10 +79,10 @@ pub trait Buf {
|
||||
/// # Examples
|
||||
///
|
||||
/// ```
|
||||
/// use bytes::{Bytes, Buf, IntoBuf};
|
||||
/// use bytes::Buf;
|
||||
/// use std::io::Cursor;
|
||||
///
|
||||
/// let bytes = Bytes::from("hello world");
|
||||
/// let mut buf = bytes.into_buf();
|
||||
/// let mut buf = Cursor::new(b"hello world");
|
||||
///
|
||||
/// assert_eq!(buf.bytes(), b"hello world");
|
||||
///
|
||||
@@ -97,15 +98,15 @@ pub trait Buf {
|
||||
|
||||
/// Returns true if there are any more bytes to consume
|
||||
///
|
||||
/// This is equivalent to `self.remaining() == 0`.
|
||||
/// This is equivalent to `self.remaining() != 0`.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```
|
||||
/// use bytes::{Bytes, Buf, IntoBuf};
|
||||
/// use bytes::Buf;
|
||||
/// use std::io::Cursor;
|
||||
///
|
||||
/// let bytes = Bytes::from("a");
|
||||
/// let mut buf = bytes.into_buf();
|
||||
/// let mut buf = Cursor::new(b"a");
|
||||
///
|
||||
/// assert!(buf.has_remaining());
|
||||
///
|
||||
@@ -391,7 +392,7 @@ pub trait Buf {
|
||||
T::read_int(&buf[..nbytes], nbytes)
|
||||
}
|
||||
|
||||
/// Gets a IEEE754 single-precision (4 bytes) floating point number from
|
||||
/// Gets an IEEE754 single-precision (4 bytes) floating point number from
|
||||
/// `self` in the specified byte order.
|
||||
///
|
||||
/// The current position is advanced by 4.
|
||||
@@ -415,7 +416,7 @@ pub trait Buf {
|
||||
T::read_f32(&buf)
|
||||
}
|
||||
|
||||
/// Gets a IEEE754 doublee-precision (8 bytes) floating point number from
|
||||
/// Gets an IEEE754 double-precision (8 bytes) floating point number from
|
||||
/// `self` in the specified byte order.
|
||||
///
|
||||
/// The current position is advanced by 8.
|
||||
@@ -470,7 +471,7 @@ pub trait Buf {
|
||||
}
|
||||
}
|
||||
|
||||
/// Creates a "by reference" adaptor for this instance of Buf
|
||||
/// Creates a "by reference" adaptor for this instance of `Buf`.
|
||||
///
|
||||
/// The returned adaptor also implements `Buf` and will simply borrow `self`.
|
||||
///
|
||||
@@ -524,38 +525,167 @@ pub trait Buf {
|
||||
}
|
||||
|
||||
/// 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 to the 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 iff there is any more space for bytes to be written
|
||||
/// 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()`.
|
||||
/// 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];
|
||||
|
||||
/// Copies bytes from `src` into `self`
|
||||
/// 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 copy all the data
|
||||
/// from `src`
|
||||
/// Panics if `self` does not have enough capacity to contain `src`.
|
||||
fn put<S: Source>(&mut self, src: S) where Self: Sized {
|
||||
src.source(self);
|
||||
src.copy_to_buf(self);
|
||||
}
|
||||
|
||||
/// Copies bytes from the given slice into the `BufMut` and advance the
|
||||
/// cursor by the number of bytes written.
|
||||
/// Returns the number of bytes written.
|
||||
/// 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;
|
||||
@@ -597,85 +727,273 @@ pub trait BufMut {
|
||||
}
|
||||
}
|
||||
|
||||
/// Writes an unsigned 16 bit integer to the BufMut.
|
||||
/// 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 the BufMut.
|
||||
/// 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 the BufMut.
|
||||
/// 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 the BufMut.
|
||||
/// 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 the BufMut.
|
||||
/// 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 the BufMut.
|
||||
/// 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-bytes integer to the BufMut.
|
||||
/// Writes an unsigned n-byte integer to `self` in the specified byte order.
|
||||
///
|
||||
/// If the given integer is not representable in the given number of bytes,
|
||||
/// this method panics. If `nbytes > 8`, this method panics.
|
||||
/// 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-bytes integer to the BufMut.
|
||||
/// Writes a signed n-byte integer to `self` in the specified byte order.
|
||||
///
|
||||
/// If the given integer is not representable in the given number of bytes,
|
||||
/// this method panics. If `nbytes > 8`, this method panics.
|
||||
/// 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 a IEEE754 single-precision (4 bytes) floating point number to
|
||||
/// the BufMut.
|
||||
/// 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 a IEEE754 double-precision (8 bytes) floating point number to
|
||||
/// the BufMut.
|
||||
/// 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
|
||||
/// 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
|
||||
}
|
||||
@@ -695,33 +1013,62 @@ pub trait BufMut {
|
||||
|
||||
/// Conversion into a `Buf`
|
||||
///
|
||||
/// Usually, `IntoBuf` is implemented on references of types and not directly
|
||||
/// on the types themselves. For example, `IntoBuf` is implemented for `&'a
|
||||
/// Vec<u8>` and not `Vec<u8>` directly.
|
||||
/// An `IntoBuf` implementation defines how to convert a value into a `Buf`.
|
||||
/// This is common for types that represent byte storage of some kind. `IntoBuf`
|
||||
/// may be implemented directly for types or on references for those types.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```
|
||||
/// use bytes::{Buf, IntoBuf, BigEndian};
|
||||
///
|
||||
/// let bytes = b"\x00\x01hello world";
|
||||
/// let mut buf = bytes.into_buf();
|
||||
///
|
||||
/// assert_eq!(1, buf.get_u16::<BigEndian>());
|
||||
///
|
||||
/// let mut rest = [0; 11];
|
||||
/// buf.copy_to_slice(&mut rest);
|
||||
///
|
||||
/// assert_eq!(b"hello world", &rest);
|
||||
/// ```
|
||||
pub trait IntoBuf {
|
||||
/// The `Buf` type that `self` is being converted into
|
||||
type Buf: Buf;
|
||||
|
||||
/// Creates a `Buf` from a value.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```
|
||||
/// use bytes::{Buf, IntoBuf, BigEndian};
|
||||
///
|
||||
/// let bytes = b"\x00\x01hello world";
|
||||
/// let mut buf = bytes.into_buf();
|
||||
///
|
||||
/// assert_eq!(1, buf.get_u16::<BigEndian>());
|
||||
///
|
||||
/// let mut rest = [0; 11];
|
||||
/// buf.copy_to_slice(&mut rest);
|
||||
///
|
||||
/// assert_eq!(b"hello world", &rest);
|
||||
/// ```
|
||||
fn into_buf(self) -> Self::Buf;
|
||||
}
|
||||
|
||||
impl<'a> IntoBuf for &'a [u8] {
|
||||
type Buf = io::Cursor<&'a [u8]>;
|
||||
|
||||
/// Creates a buffer from a value
|
||||
fn into_buf(self) -> Self::Buf {
|
||||
io::Cursor::new(self)
|
||||
}
|
||||
}
|
||||
|
||||
// Kind of annoying...
|
||||
impl<'a> IntoBuf for &'a &'static [u8] {
|
||||
type Buf = io::Cursor<&'static [u8]>;
|
||||
impl<'a> IntoBuf for &'a str {
|
||||
type Buf = io::Cursor<&'a [u8]>;
|
||||
|
||||
/// Creates a buffer from a value
|
||||
fn into_buf(self) -> Self::Buf {
|
||||
io::Cursor::new(self)
|
||||
self.as_bytes().into_buf()
|
||||
}
|
||||
}
|
||||
|
||||
@@ -733,6 +1080,24 @@ impl IntoBuf for Vec<u8> {
|
||||
}
|
||||
}
|
||||
|
||||
// Kind of annoying... but this impl is required to allow passing `&'static
|
||||
// [u8]` where for<'a> &'a T: IntoBuf is required.
|
||||
impl<'a> IntoBuf for &'a &'static [u8] {
|
||||
type Buf = io::Cursor<&'static [u8]>;
|
||||
|
||||
fn into_buf(self) -> Self::Buf {
|
||||
io::Cursor::new(self)
|
||||
}
|
||||
}
|
||||
|
||||
impl<'a> IntoBuf for &'a &'static str {
|
||||
type Buf = io::Cursor<&'static [u8]>;
|
||||
|
||||
fn into_buf(self) -> Self::Buf {
|
||||
self.as_bytes().into_buf()
|
||||
}
|
||||
}
|
||||
|
||||
impl<'a> IntoBuf for &'a Vec<u8> {
|
||||
type Buf = io::Cursor<&'a [u8]>;
|
||||
|
||||
@@ -741,6 +1106,22 @@ impl<'a> IntoBuf for &'a Vec<u8> {
|
||||
}
|
||||
}
|
||||
|
||||
impl IntoBuf for String {
|
||||
type Buf = io::Cursor<Vec<u8>>;
|
||||
|
||||
fn into_buf(self) -> Self::Buf {
|
||||
self.into_bytes().into_buf()
|
||||
}
|
||||
}
|
||||
|
||||
impl<'a> IntoBuf for &'a String {
|
||||
type Buf = io::Cursor<&'a [u8]>;
|
||||
|
||||
fn into_buf(self) -> Self::Buf {
|
||||
self.as_bytes().into_buf()
|
||||
}
|
||||
}
|
||||
|
||||
impl IntoBuf for () {
|
||||
type Buf = io::Cursor<&'static [u8]>;
|
||||
|
||||
@@ -765,50 +1146,120 @@ impl<'a> IntoBuf for &'a () {
|
||||
|
||||
|
||||
/// A value that writes bytes from itself into a `BufMut`.
|
||||
///
|
||||
/// Values that implement `Source` are used as an argument to
|
||||
/// [`BufMut::put`](trait.BufMut.html#method.put).
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```
|
||||
/// use bytes::{BufMut, Source};
|
||||
///
|
||||
/// struct Repeat {
|
||||
/// num: usize,
|
||||
/// str: String,
|
||||
/// }
|
||||
///
|
||||
/// impl Source for Repeat {
|
||||
/// fn copy_to_buf<B: BufMut>(self, buf: &mut B) {
|
||||
/// for _ in 0..self.num {
|
||||
/// buf.put(&self.str);
|
||||
/// }
|
||||
/// }
|
||||
/// }
|
||||
///
|
||||
/// let mut dst = vec![];
|
||||
/// dst.put(Repeat {
|
||||
/// num: 3,
|
||||
/// str: "hello".into(),
|
||||
/// });
|
||||
///
|
||||
/// assert_eq!(*dst, b"hellohellohello"[..]);
|
||||
/// ```
|
||||
pub trait Source {
|
||||
/// Copy data from self into destination buffer
|
||||
fn source<B: BufMut>(self, buf: &mut B);
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```
|
||||
/// use bytes::{BufMut, Source};
|
||||
///
|
||||
/// let mut dst = vec![];
|
||||
///
|
||||
/// "hello".copy_to_buf(&mut dst);
|
||||
///
|
||||
/// assert_eq!(*dst, b"hello"[..]);
|
||||
/// ```
|
||||
///
|
||||
/// # Panics
|
||||
///
|
||||
/// This function panis if `buf` does not have enough capacity for `self`.
|
||||
fn copy_to_buf<B: BufMut>(self, buf: &mut B);
|
||||
}
|
||||
|
||||
impl Source for Vec<u8> {
|
||||
fn copy_to_buf<B: BufMut>(self, buf: &mut B) {
|
||||
buf.put_slice(&self[..]);
|
||||
}
|
||||
}
|
||||
|
||||
impl<'a> Source for &'a Vec<u8> {
|
||||
fn copy_to_buf<B: BufMut>(self, buf: &mut B) {
|
||||
buf.put_slice(&self[..]);
|
||||
}
|
||||
}
|
||||
|
||||
impl<'a> Source for &'a [u8] {
|
||||
fn source<B: BufMut>(self, buf: &mut B) {
|
||||
fn copy_to_buf<B: BufMut>(self, buf: &mut B) {
|
||||
buf.put_slice(self);
|
||||
}
|
||||
}
|
||||
|
||||
impl Source for String {
|
||||
fn copy_to_buf<B: BufMut>(self, buf: &mut B) {
|
||||
buf.put_slice(self.as_bytes());
|
||||
}
|
||||
}
|
||||
|
||||
impl<'a> Source for &'a String {
|
||||
fn copy_to_buf<B: BufMut>(self, buf: &mut B) {
|
||||
buf.put_slice(self.as_bytes());
|
||||
}
|
||||
}
|
||||
|
||||
impl<'a> Source for &'a str {
|
||||
fn source<B: BufMut>(self, buf: &mut B) {
|
||||
fn copy_to_buf<B: BufMut>(self, buf: &mut B) {
|
||||
buf.put_slice(self.as_bytes());
|
||||
}
|
||||
}
|
||||
|
||||
impl Source for u8 {
|
||||
fn source<B: BufMut>(self, buf: &mut B) {
|
||||
fn copy_to_buf<B: BufMut>(self, buf: &mut B) {
|
||||
let src = [self];
|
||||
buf.put_slice(&src);
|
||||
}
|
||||
}
|
||||
|
||||
impl Source for i8 {
|
||||
fn source<B: BufMut>(self, buf: &mut B) {
|
||||
fn copy_to_buf<B: BufMut>(self, buf: &mut B) {
|
||||
buf.put_slice(&[self as u8])
|
||||
}
|
||||
}
|
||||
|
||||
impl Source for Bytes {
|
||||
fn source<B: BufMut>(self, buf: &mut B) {
|
||||
Source::source(self.as_ref(), buf);
|
||||
fn copy_to_buf<B: BufMut>(self, buf: &mut B) {
|
||||
Source::copy_to_buf(self.as_ref(), buf);
|
||||
}
|
||||
}
|
||||
|
||||
impl<'a> Source for &'a Bytes {
|
||||
fn source<B: BufMut>(self, buf: &mut B) {
|
||||
Source::source(self.as_ref(), buf);
|
||||
fn copy_to_buf<B: BufMut>(self, buf: &mut B) {
|
||||
Source::copy_to_buf(self.as_ref(), buf);
|
||||
}
|
||||
}
|
||||
|
||||
impl<'a, T: Buf> Source for &'a mut T {
|
||||
fn source<B: BufMut>(mut self, buf: &mut B) {
|
||||
impl<T: Buf> Source for T {
|
||||
fn copy_to_buf<B: BufMut>(mut self, buf: &mut B) {
|
||||
assert!(buf.remaining_mut() >= self.remaining());
|
||||
|
||||
while self.has_remaining() {
|
||||
@@ -839,8 +1290,8 @@ impl<'a, T: Buf> Source for &'a mut T {
|
||||
|
||||
/// A `Buf` adapter which limits the bytes read from an underlying buffer.
|
||||
///
|
||||
/// This struct is generally created by calling `take()` on `Buf`. [More
|
||||
/// detail](trait.Buf.html#method.take).
|
||||
/// This struct is generally created by calling `take()` on `Buf`. See
|
||||
/// documentation of [`take()`](trait.Buf.html#method.take) for more details.
|
||||
pub struct Take<T> {
|
||||
inner: T,
|
||||
limit: usize,
|
||||
@@ -848,28 +1299,117 @@ pub struct Take<T> {
|
||||
|
||||
impl<T> Take<T> {
|
||||
/// Consumes this `Take`, returning the underlying value.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```rust
|
||||
/// use bytes::{Buf, BufMut};
|
||||
/// use std::io::Cursor;
|
||||
///
|
||||
/// let mut buf = Cursor::new(b"hello world").take(2);
|
||||
/// let mut dst = vec![];
|
||||
///
|
||||
/// dst.put(&mut buf);
|
||||
/// assert_eq!(*dst, b"he"[..]);
|
||||
///
|
||||
/// let mut buf = buf.into_inner();
|
||||
///
|
||||
/// dst.clear();
|
||||
/// dst.put(&mut buf);
|
||||
/// assert_eq!(*dst, b"llo world"[..]);
|
||||
/// ```
|
||||
pub fn into_inner(self) -> T {
|
||||
self.inner
|
||||
}
|
||||
|
||||
/// Gets a reference to the underlying value in this `Take`.
|
||||
/// Gets a reference to the underlying `Buf`.
|
||||
///
|
||||
/// It is inadvisable to directly read from the underlying reader.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```rust
|
||||
/// use bytes::{Buf, BufMut};
|
||||
/// use std::io::Cursor;
|
||||
///
|
||||
/// let mut buf = Cursor::new(b"hello world").take(2);
|
||||
///
|
||||
/// assert_eq!(0, buf.get_ref().position());
|
||||
/// ```
|
||||
pub fn get_ref(&self) -> &T {
|
||||
&self.inner
|
||||
}
|
||||
|
||||
/// Gets a mutable reference to the underlying value in this `Take`.
|
||||
/// Gets a mutable reference to the underlying `Buf`.
|
||||
///
|
||||
/// It is inadvisable to directly read from the underlying reader.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```rust
|
||||
/// use bytes::{Buf, BufMut};
|
||||
/// use std::io::Cursor;
|
||||
///
|
||||
/// let mut buf = Cursor::new(b"hello world").take(2);
|
||||
/// let mut dst = vec![];
|
||||
///
|
||||
/// buf.get_mut().set_position(2);
|
||||
///
|
||||
/// dst.put(&mut buf);
|
||||
/// assert_eq!(*dst, b"ll"[..]);
|
||||
/// ```
|
||||
pub fn get_mut(&mut self) -> &mut T {
|
||||
&mut self.inner
|
||||
}
|
||||
|
||||
/// Returns the maximum number of bytes that are made available from the
|
||||
/// underlying value.
|
||||
/// Returns the maximum number of bytes that can be read.
|
||||
///
|
||||
/// # Note
|
||||
///
|
||||
/// If the inner `Buf` has fewer bytes than indicated by this method then
|
||||
/// that is the actual number of available bytes.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```rust
|
||||
/// use bytes::Buf;
|
||||
/// use std::io::Cursor;
|
||||
///
|
||||
/// let mut buf = Cursor::new(b"hello world").take(2);
|
||||
///
|
||||
/// assert_eq!(2, buf.limit());
|
||||
/// assert_eq!(b'h', buf.get_u8());
|
||||
/// assert_eq!(1, buf.limit());
|
||||
/// ```
|
||||
pub fn limit(&self) -> usize {
|
||||
self.limit
|
||||
}
|
||||
|
||||
/// Sets the maximum number of bytes that are made available from the
|
||||
/// underlying value.
|
||||
/// Sets the maximum number of bytes that can be read.
|
||||
///
|
||||
/// # Note
|
||||
///
|
||||
/// If the inner `Buf` has fewer bytes than `lim` then that is the actual
|
||||
/// number of available bytes.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```rust
|
||||
/// use bytes::{Buf, BufMut};
|
||||
/// use std::io::Cursor;
|
||||
///
|
||||
/// let mut buf = Cursor::new(b"hello world").take(2);
|
||||
/// let mut dst = vec![];
|
||||
///
|
||||
/// dst.put(&mut buf);
|
||||
/// assert_eq!(*dst, b"he"[..]);
|
||||
///
|
||||
/// dst.clear();
|
||||
///
|
||||
/// buf.set_limit(3);
|
||||
/// dst.put(&mut buf);
|
||||
/// assert_eq!(*dst, b"llo"[..]);
|
||||
/// ```
|
||||
pub fn set_limit(&mut self, lim: usize) {
|
||||
self.limit = lim
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user