tokio-rs/bytes
1
0
Fork 0
mirror of https://github.com/tokio-rs/bytes.git synced 2026-08-12 00:00:14 +02:00
Code Issues Packages Projects Releases Wiki Activity

Docs & polish for Buf

Browse Source
This commit is contained in:
Carl Lerche
2017-02-16 22:15:17 -08:00
parent 268226051d
commit 5048eec143
3 changed files with 422 additions and 54 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/buf.rs
+419 -42
View File
@@ -20,43 +20,113 @@ use std::{cmp, io, ptr, usize};
/// assert_eq!(b'e', buf.get_u8());
/// assert_eq!(b'l', buf.get_u8());
///
/// let mut rest = vec![];
/// buf.copy_to(&mut rest);
/// let mut rest = [0; 8];
/// buf.copy_to_slice(&mut rest);
///
/// assert_eq!(&rest[..], b"lo world");
/// ```
pub trait Buf {
/// Returns the number of bytes that can be accessed from the Buf
/// Returns the number of bytes between the current position and the end of
/// the buffer.
///
/// This value is greater than or equal to the length of the slice returned
/// by `bytes`.
///
/// # Examples
///
/// ```
/// use bytes::{Bytes, Buf, IntoBuf};
///
/// let bytes = Bytes::from("hello world");
/// let mut buf = bytes.into_buf();
///
/// assert_eq!(buf.remaining(), 11);
///
/// buf.get_u8();
///
/// assert_eq!(buf.remaining(), 10);
/// ```
fn remaining(&self) -> usize;
/// Returns a slice starting at the current Buf position and of length
/// between 0 and `Buf::remaining()`.
/// Returns a slice starting at the current position and of length between 0
/// and `Buf::remaining()`.
///
/// This is a lower level function. Most operations are done with other
/// functions.
///
/// # Examples
///
/// ```
/// use bytes::{Bytes, Buf, IntoBuf};
///
/// let bytes = Bytes::from("hello world");
/// let mut buf = bytes.into_buf();
///
/// assert_eq!(buf.bytes(), b"hello world");
///
/// buf.advance(6);
///
/// assert_eq!(buf.bytes(), b"world");
/// ```
fn bytes(&self) -> &[u8];
/// Advance the internal cursor of the Buf
///
/// The next call to `bytes` will return a slice starting `cnt` bytes
/// further into the underlying buffer.
///
/// # Examples
///
/// ```
/// use bytes::{Bytes, Buf, IntoBuf};
///
/// let bytes = Bytes::from("hello world");
/// let mut buf = bytes.into_buf();
///
/// assert_eq!(buf.bytes(), b"hello world");
///
/// buf.advance(6);
///
/// assert_eq!(buf.bytes(), b"world");
/// ```
///
/// # Panics
///
/// This function can panic if `cnt > self.remaining()`.
fn advance(&mut self, cnt: usize);
/// Returns true if there are any more bytes to consume
///
/// This is equivalent to `self.remaining() == 0`.
///
/// # Examples
///
/// ```
/// use bytes::{Bytes, Buf, IntoBuf};
///
/// let bytes = Bytes::from("a");
/// let mut buf = bytes.into_buf();
///
/// assert!(buf.has_remaining());
///
/// buf.get_u8();
///
/// assert!(!buf.has_remaining());
/// ```
fn has_remaining(&self) -> bool {
self.remaining() > 0
}
/// Copies bytes from `self` into `dst`
/// Copies bytes from `self` into `dst`.
///
/// # Panics
/// The cursor is advanced by the number of bytes copied. `self` must have
/// enough remaining bytes to fill `dst`.
///
/// The function panics if `self` does not contain enough bytes to fill
/// `dst`.
fn copy_to<S: Sink + ?Sized>(&mut self, dst: &mut S) where Self: Sized {
dst.sink(self);
}
/// Copies bytes from the `Buf` into the given slice and advance the cursor by
/// the number of bytes copied.
/// # Examples
///
/// ```
/// use std::io::Cursor;
/// use bytes::Buf;
/// use std::io::Cursor;
///
/// let mut buf = Cursor::new(b"hello world");
/// let mut dst = [0; 5];
@@ -91,70 +161,230 @@ pub trait Buf {
}
}
/// Gets an unsigned 8 bit integer from the `Buf`.
/// Gets an unsigned 8 bit integer from `self`.
///
/// The current position is advanced by 1.
///
/// # Examples
///
/// ```
/// use bytes::Buf;
/// use std::io::Cursor;
///
/// let mut buf = Cursor::new(b"\x08 hello");
/// assert_eq!(8, buf.get_u8());
/// ```
///
/// # Panics
///
/// This function panics if there is no more remaining data in `self`.
fn get_u8(&mut self) -> u8 {
let mut buf = [0; 1];
self.copy_to_slice(&mut buf);
buf[0]
}
/// Gets a signed 8 bit integer from the `Buf`.
/// Gets a signed 8 bit integer from `self`.
///
/// The current position is advanced by 1.
///
/// # Examples
///
/// ```
/// use bytes::Buf;
/// use std::io::Cursor;
///
/// let mut buf = Cursor::new(b"\x08 hello");
/// assert_eq!(8, buf.get_i8());
/// ```
///
/// # Panics
///
/// This function panics if there is no more remaining data in `self`.
fn get_i8(&mut self) -> i8 {
let mut buf = [0; 1];
self.copy_to_slice(&mut buf);
buf[0] as i8
}
/// Gets an unsigned 16 bit integer from the `Buf`
/// Gets an unsigned 16 bit integer from `self` in the specified byte order.
///
/// The current position is advanced by 2.
///
/// # Examples
///
/// ```
/// use bytes::{Buf, BigEndian};
/// use std::io::Cursor;
///
/// let mut buf = Cursor::new(b"\x08\x09 hello");
/// assert_eq!(0x0809, buf.get_u16::<BigEndian>());
/// ```
///
/// # Panics
///
/// This function panics if there is not enough remaining data in `self`.
fn get_u16<T: ByteOrder>(&mut self) -> u16 {
let mut buf = [0; 2];
self.copy_to_slice(&mut buf);
T::read_u16(&buf)
}
/// Gets a signed 16 bit integer from the `Buf`
/// Gets a signed 16 bit integer from `self` in the specified byte order.
///
/// The current position is advanced by 2.
///
/// # Examples
///
/// ```
/// use bytes::{Buf, BigEndian};
/// use std::io::Cursor;
///
/// let mut buf = Cursor::new(b"\x08\x09 hello");
/// assert_eq!(0x0809, buf.get_i16::<BigEndian>());
/// ```
///
/// # Panics
///
/// This function panics if there is not enough remaining data in `self`.
fn get_i16<T: ByteOrder>(&mut self) -> i16 {
let mut buf = [0; 2];
self.copy_to_slice(&mut buf);
T::read_i16(&buf)
}
/// Gets an unsigned 32 bit integer from the `Buf`
/// Gets an unsigned 32 bit integer from `self` in the specified byte order.
///
/// The current position is advanced by 4.
///
/// # Examples
///
/// ```
/// use bytes::{Buf, BigEndian};
/// use std::io::Cursor;
///
/// let mut buf = Cursor::new(b"\x08\x09\xA0\xA1 hello");
/// assert_eq!(0x0809A0A1, buf.get_u32::<BigEndian>());
/// ```
///
/// # Panics
///
/// This function panics if there is not enough remaining data in `self`.
fn get_u32<T: ByteOrder>(&mut self) -> u32 {
let mut buf = [0; 4];
self.copy_to_slice(&mut buf);
T::read_u32(&buf)
}
/// Gets a signed 32 bit integer from the `Buf`
/// Gets a signed 32 bit integer from `self` in the specified byte order.
///
/// The current position is advanced by 4.
///
/// # Examples
///
/// ```
/// use bytes::{Buf, BigEndian};
/// use std::io::Cursor;
///
/// let mut buf = Cursor::new(b"\x08\x09\xA0\xA1 hello");
/// assert_eq!(0x0809A0A1, buf.get_i32::<BigEndian>());
/// ```
///
/// # Panics
///
/// This function panics if there is not enough remaining data in `self`.
fn get_i32<T: ByteOrder>(&mut self) -> i32 {
let mut buf = [0; 4];
self.copy_to_slice(&mut buf);
T::read_i32(&buf)
}
/// Gets an unsigned 64 bit integer from the `Buf`
/// Gets an unsigned 64 bit integer from `self` in the specified byte order.
///
/// The current position is advanced by 8.
///
/// # Examples
///
/// ```
/// use bytes::{Buf, BigEndian};
/// use std::io::Cursor;
///
/// let mut buf = Cursor::new(b"\x01\x02\x03\x04\x05\x06\x07\x08 hello");
/// assert_eq!(0x0102030405060708, buf.get_u64::<BigEndian>());
/// ```
///
/// # Panics
///
/// This function panics if there is not enough remaining data in `self`.
fn get_u64<T: ByteOrder>(&mut self) -> u64 {
let mut buf = [0; 8];
self.copy_to_slice(&mut buf);
T::read_u64(&buf)
}
/// Gets a signed 64 bit integer from the `Buf`
/// Gets a signed 64 bit integer from `self` in the specified byte order.
///
/// The current position is advanced by 8.
///
/// # Examples
///
/// ```
/// use bytes::{Buf, BigEndian};
/// use std::io::Cursor;
///
/// let mut buf = Cursor::new(b"\x01\x02\x03\x04\x05\x06\x07\x08 hello");
/// assert_eq!(0x0102030405060708, buf.get_i64::<BigEndian>());
/// ```
///
/// # Panics
///
/// This function panics if there is not enough remaining data in `self`.
fn get_i64<T: ByteOrder>(&mut self) -> i64 {
let mut buf = [0; 8];
self.copy_to_slice(&mut buf);
T::read_i64(&buf)
}
/// Gets an unsigned n-bytes integer from the `Buf`
/// Gets an unsigned n-byte integer from `self` in the specified byte order.
///
/// The current position is advanced by `nbytes`.
///
/// # Examples
///
/// ```
/// use bytes::{Buf, BigEndian};
/// use std::io::Cursor;
///
/// let mut buf = Cursor::new(b"\x01\x02\x03 hello");
/// assert_eq!(0x010203, buf.get_uint::<BigEndian>(3));
/// ```
///
/// # Panics
///
/// This function panics if there is not enough remaining data in `self`.
fn get_uint<T: ByteOrder>(&mut self, nbytes: usize) -> u64 {
let mut buf = [0; 8];
self.copy_to_slice(&mut buf[..nbytes]);
T::read_uint(&buf[..nbytes], nbytes)
}
/// Gets a signed n-bytes integer from the `Buf`
/// Gets a signed n-byte integer from `self` in the specified byte order.
///
/// The current position is advanced by `nbytes`.
///
/// # Examples
///
/// ```
/// use bytes::{Buf, BigEndian};
/// use std::io::Cursor;
///
/// let mut buf = Cursor::new(b"\x01\x02\x03 hello");
/// assert_eq!(0x010203, buf.get_int::<BigEndian>(3));
/// ```
///
/// # Panics
///
/// This function panics if there is not enough remaining data in `self`.
fn get_int<T: ByteOrder>(&mut self, nbytes: usize) -> i64 {
let mut buf = [0; 8];
self.copy_to_slice(&mut buf[..nbytes]);
@@ -162,27 +392,132 @@ pub trait Buf {
}
/// Gets a IEEE754 single-precision (4 bytes) floating point number from
/// the `Buf`
/// `self` in the specified byte order.
///
/// The current position is advanced by 4.
///
/// # Examples
///
/// ```
/// use bytes::{Buf, BigEndian};
/// use std::io::Cursor;
///
/// let mut buf = Cursor::new(b"\x3F\x99\x99\x9A hello");
/// assert_eq!(1.2f32, buf.get_f32::<BigEndian>());
/// ```
///
/// # Panics
///
/// This function panics if there is not enough remaining data in `self`.
fn get_f32<T: ByteOrder>(&mut self) -> f32 {
let mut buf = [0; 4];
self.copy_to_slice(&mut buf);
T::read_f32(&buf)
}
/// Gets a IEEE754 double-precision (8 bytes) floating point number from
/// the `Buf`
/// Gets a IEEE754 doublee-precision (8 bytes) floating point number from
/// `self` in the specified byte order.
///
/// The current position is advanced by 8.
///
/// # Examples
///
/// ```
/// use bytes::{Buf, BigEndian};
/// use std::io::Cursor;
///
/// let mut buf = Cursor::new(b"\x3F\xF3\x33\x33\x33\x33\x33\x33 hello");
/// assert_eq!(1.2f64, buf.get_f64::<BigEndian>());
/// ```
///
/// # Panics
///
/// This function panics if there is not enough remaining data in `self`.
fn get_f64<T: ByteOrder>(&mut self) -> f64 {
let mut buf = [0; 8];
self.copy_to_slice(&mut buf);
T::read_f64(&buf)
}
/// Creates an adaptor which will read at most `limit` bytes from `self`.
///
/// This function returns a new instance of `Buf` which will read at most
/// `limit` bytes.
///
/// # Examples
///
/// ```
/// use bytes::{Buf, BufMut};
/// use std::io::Cursor;
///
/// let mut buf = Cursor::new("hello world").take(5);
/// let mut dst = vec![];
///
/// dst.put(&mut buf);
/// assert_eq!(dst, b"hello");
///
/// let mut buf = buf.into_inner();
/// dst.clear();
/// dst.put(&mut buf);
/// assert_eq!(dst, b" world");
/// ```
fn take(self, limit: usize) -> Take<Self>
where Self: Sized
{
Take {
inner: self,
limit: limit,
}
}
/// Creates a "by reference" adaptor for this instance of Buf
///
/// The returned adaptor also implements `Buf` and will simply borrow `self`.
///
/// # Examples
///
/// ```
/// use bytes::{Buf, BufMut};
/// use std::io::Cursor;
///
/// let mut buf = Cursor::new("hello world");
/// let mut dst = vec![];
///
/// {
/// let mut reference = buf.by_ref();
/// dst.put(&mut reference.take(5));
/// assert_eq!(dst, b"hello");
/// } // drop our &mut reference so we can use `buf` again
///
/// dst.clear();
/// dst.put(&mut buf);
/// assert_eq!(dst, b" world");
/// ```
fn by_ref(&mut self) -> &mut Self where Self: Sized {
self
}
/// Return a `Reader` for the value. Allows using a `Buf` as an `io::Read`
/// Creates an adaptor which implements the `Read` trait for `self`.
///
/// This function returns a new value which implements `Read` by adapting
/// the `Read` trait functions to the `Buf` trait functions.
///
/// # Examples
///
/// ```
/// use bytes::{Buf, IntoBuf, Bytes};
/// use std::io::Read;
///
/// let buf = Bytes::from("hello world").into_buf();
///
/// let mut reader = buf.reader();
/// let mut dst = [0; 1024];
///
/// let num = reader.read(&mut dst).unwrap();
///
/// assert_eq!(11, num);
/// assert_eq!(&dst[..11], b"hello world");
/// ```
fn reader(self) -> Reader<Self> where Self: Sized {
Reader::new(self)
}
@@ -424,7 +759,7 @@ impl<'a> IntoBuf for &'a () {
/*
*
* ===== Sink / Source =====
* ===== Source =====
*
*/
@@ -496,21 +831,63 @@ impl<'a, T: Buf> Source for &'a mut T {
}
}
/// A value that copies bytes from a `Buf` into itself
pub trait Sink {
/// Copy bytes from `buf` into `self`
fn sink<B: Buf>(&mut self, buf: &mut B);
/*
*
* ===== Take =====
*
*/
/// 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).
pub struct Take<T> {
inner: T,
limit: usize,
}
impl Sink for [u8] {
fn sink<B: Buf>(&mut self, buf: &mut B) {
buf.copy_to_slice(self);
impl<T> Take<T> {
/// Consumes this `Take`, returning the underlying value.
pub fn into_inner(self) -> T {
self.inner
}
/// Gets a reference to the underlying value in this `Take`.
pub fn get_ref(&self) -> &T {
&self.inner
}
/// Gets a mutable reference to the underlying value in this `Take`.
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.
pub fn limit(&self) -> usize {
self.limit
}
/// Sets the maximum number of bytes that are made available from the
/// underlying value.
pub fn set_limit(&mut self, lim: usize) {
self.limit = lim
}
}
impl<T: BufMut> Sink for T {
fn sink<B: Buf>(&mut self, buf: &mut B) {
Source::source(buf, self)
impl<T: Buf> Buf for Take<T> {
fn remaining(&self) -> usize {
cmp::min(self.inner.remaining(), self.limit)
}
fn bytes(&self) -> &[u8] {
&self.inner.bytes()[..self.limit]
}
fn advance(&mut self, cnt: usize) {
let cnt = cmp::min(cnt, self.limit);
self.limit -= cnt;
self.inner.advance(cnt);
}
}
@@ -551,7 +928,7 @@ impl<B: Buf + Sized> io::Read for Reader<B> {
fn read(&mut self, dst: &mut [u8]) -> io::Result<usize> {
let len = cmp::min(self.buf.remaining(), dst.len());
Buf::copy_to(&mut self.buf, &mut dst[0..len]);
Buf::copy_to_slice(&mut self.buf, &mut dst[0..len]);
Ok(len)
}
}
src/lib.rs
+2 -1
View File
@@ -75,8 +75,9 @@ pub use buf::{
BufMut,
IntoBuf,
Source,
Sink,
Reader,
Writer,
Take,
};
pub use bytes::{Bytes, BytesMut};
pub use byteorder::{ByteOrder, BigEndian, LittleEndian};
tests/test_buf.rs
+1 -11
View File
@@ -1,7 +1,7 @@
extern crate bytes;
extern crate byteorder;
use bytes::{Buf, Sink};
use bytes::Buf;
use std::io::Cursor;
#[test]
@@ -46,13 +46,3 @@ fn test_get_u16_buffer_underflow() {
let mut buf = Cursor::new(b"\x21");
buf.get_u16::<byteorder::BigEndian>();
}
#[test]
fn test_vec_sink_capacity() {
let mut sink: Vec<u8> = Vec::new();
sink.reserve(16);
assert!(sink.capacity() >= 16, "Capacity {} must be at least 16", sink.capacity());
let mut source = Cursor::new(b"0123456789abcdef0123456789abcdef");
sink.sink(&mut source);
assert!(sink.len() <= sink.capacity(), "Length {} must be less than or equal to capacity {}", sink.len(), sink.capacity());
}