Docs & polish for Buf

src/buf.rs

@@ -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

@@ -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

 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());
-}